Cloud CMS Application Server

Common errors

• Error: Configuration for store 'oneteam' not found

  cause The `storeConfigurations` block refers to a `storeEngine` name (e.g., 'oneteam') that is not defined in the `storeEngines` block, or a typo exists.
  fix Ensure all store names referenced within `storeConfigurations` exactly match a defined `type` within the `storeEngines` object. Double-check for typos.

• Failed to start Cloud CMS Application Server: Error: Missing accessKeyId in config

  cause An S3 or S3FS `storeEngine` is enabled and configured, but the required AWS credentials (`accessKey` or `secretKey`) are missing or empty in its configuration.
  fix Provide valid `accessKey` and `secretKey` within the `config` object for any S3 or S3FS store engines. It is recommended to use environment variables (e.g., `process.env.AWS_ACCESS_KEY_ID`) for these sensitive credentials.

• TypeError: Cannot read properties of undefined (reading 'start')

  cause The `cloudcms-server` module was imported incorrectly, resulting in `cloudcmsServer` being `undefined` or not having a `start` method.
  fix For CommonJS, use `const cloudcmsServer = require('cloudcms-server');`. For ESM, use `import cloudcmsServer from 'cloudcms-server';`. Avoid named imports for the main server object.

Warnings

• gotcha The configuration object, especially `storeEngines` and `storeConfigurations`, is complex and critical for correct server operation. Misconfigurations in paths, types, or credentials for storage can lead to startup failures or runtime errors.
  Fix: Carefully review the provided configuration examples and ensure all paths are correct for your deployment environment. Validate `accessKey`, `secretKey`, and `bucket` for S3 configurations. Use environment variables for sensitive data.
• gotcha When enabling S3 or S3FS store engines, the underlying AWS SDK (or similar) library is a runtime dependency. While `cloudcms-server` might not explicitly list `aws-sdk` in its `package.json`'s dependencies, you may need to install it manually in your project (`npm install aws-sdk`) to ensure S3 functionality works correctly.
  Fix: If using S3 storage, run `npm install aws-sdk` (or equivalent for your package manager) in your project to provide the necessary runtime dependency.
• gotcha Many advanced features like `wcm`, `virtualHost`, `insight`, and `serverTags` are disabled by default in the provided configuration snippet. If you intend to use these features, you must explicitly enable them in your `serverConfig` object.
  Fix: Check the `wcm.enabled`, `virtualHost.enabled`, `insight.enabled`, etc., flags in your configuration and set them to `true` as required for your application's functionality.

Install

• npm install cloudcms-server npm
• yarn add cloudcms-server yarn
• pnpm add cloudcms-server pnpm

Imports

• cloudcmsServer
  wrong:

  import { cloudcmsServer } from 'cloudcms-server';

  correct:

  import cloudcmsServer from 'cloudcms-server';

  The primary entry point is likely a default export, providing the main server object. While CommonJS `require` is also supported, ESM is preferred for modern applications.
• start
  wrong:

  import { start } from 'cloudcms-server';

  correct:

  const cloudcmsServer = require('cloudcms-server');
  cloudcmsServer.start(config);

  The `start` method is invoked on the main server object obtained from the module's default export, not as a named export directly from the package root.
• Server Configuration
  wrong:

  const config = require('./config.json');

  correct:

  const config = { /* ... */ };

  While configuration can be loaded from a file, the server expects a JavaScript object directly for its `start` method. Ensure the object structure matches the server's expectations.

Quickstart

This quickstart initializes and starts a `cloudcms-server` instance with a basic configuration, including a custom route and WCM enabled. It demonstrates how to import the server module, define its configuration, and handle startup.

import cloudcmsServer from 'cloudcms-server';

const serverConfig = {
    "setup": "single",
    "name": "My Cloud CMS Application",
    "socketFunctions": [],
    "routeFunctions": [
        async function(req, res, next) {
            if (req.url === '/') {
                return res.send('Welcome to your Cloud CMS powered application!');
            }
            next();
        }
    ],
    "errorFunctions": [],
    "configureFunctions": {},
    "viewEngine": "handlebars",
    "wcm": {
        "enabled": true, // Enable WCM features
        "cache": false
    },
    "auth": {
        "enabled": true,
        "providers": {}
    },
    "port": process.env.PORT ?? 3000,
    "host": process.env.HOST ?? '0.0.0.0'
};

async function startServer() {
    try {
        const server = await cloudcmsServer.start(serverConfig);
        console.log(`Cloud CMS Application Server started successfully on port ${server.port}`);
        console.log('Access it at http://localhost:' + server.port);
    } catch (err) {
        console.error('Failed to start Cloud CMS Application Server:', err);
        process.exit(1);
    }
}

startServer();