UI Server

The Cloud CMS UI Server is a Node.js application that provides the editorial experience for Cloud CMS. It communicates with the Cloud CMS API via HTTP/HTTPS API calls and is built to be very extensible. Developers and system integrators can extend the Cloud CMS UI through the deployment of UI modules.

Environment File (.env)

The Cloud CMS UI is primarily configured via a series of environment variables. These environment variables are detected by the Node.js application at startup and the values specified therein are used to override the default settings. You can use environment variables to configure a variety of global aspects about the Cloud CMS UI Server.

Since the Cloud CMS UI Server is launched within a Docker container, you have a variety of means at your disposal for providing these variables. The most common mechanism is to utilize a environments file (ui.env) and configure the Docker runtime to launch with those variables. This is the configuration the Cloud CMS provides with its own sample Docker kits.

Environment Variables

The following environment variables are supported:

Proxy

The following variables should be set to point to the location of the Cloud CMS API server (from the UI Server's perspective).

GITANA_PROXY_SCHEME=http
GITANA_PROXY_HOST=api
GITANA_PROXY_PORT=8080

If you're running in a simple configuration with a single UI Server and a single API server running on a common Docker host, then these variables should point to the container service ID of the API Server (such as api) as configured in your Docker network (or via Compose).

If you're running in a more complex configuration where you have a load balancer involved (ahead of multiple API Servers), then the host should be the resolvable domain name or IP address of the load balancer.

Be sure to check that the port is correct as well. To verify this, we often recommend logging into the container (sometimes referred to as "bashing into" the container). If you open a bash session within the container, you can then try to connect to the API Server manually (at the specified host and port). Something as basic as telnet can be used for this but there are other tools out there as well.

If you're unable to manually connect from the UI container to the API container, then the Cloud CMS UI Server will not be able to connect either.

Virtual Driver

The UI Server maintains a special "virtual driver" connection that allows it to manage connections and perform other book keeping operations. These virtual driver settings must match those that are found in the API Server's docker.properties file.

In the API Server's docker.properties file, you'll have entries like these:

cloudcmsnet.virtualdriver.clientKey=
cloudcmsnet.virtualdriver.clientSecret=
cloudcmsnet.virtualdriver.authGrantKey=
cloudcmsnet.virtualdriver.authGrantSecret=
cloudcmsnet.virtualdriver.username=
cloudcmsnet.virtualdriver.password=

You environment variables should be configured to point to these values, like this:

CLOUDCMS_VIRTUAL_DRIVER_CLIENT_KEY=<value of cloudcmsnet.virtualdriver.clientKey>
CLOUDCMS_VIRTUAL_DRIVER_CLIENT_SECRET=<value of cloudcmsnet.virtualdriver.clientSecret>
CLOUDCMS_VIRTUAL_DRIVER_AUTHGRANT_KEY=<value of cloudcmsnet.virtualdriver.authGrantKey>
CLOUDCMS_VIRTUAL_DRIVER_AUTHGRANT_SECRET=<value of cloudcmsnet.virtualdriver.authGrantSecret>
CLOUDCMS_VIRTUAL_DRIVER_BASE_URL=http://api:8080

Be sure to adjust the value of the CLOUDCMS_VIRTUAL_DRIVER_BASE_URL to take into account the same considerations as the Proxy section above. The virtual driver needs to be able to connect to the API Server so make sure the correct host and port are used.

Notifications

You will also want to make sure that you have a Notifications message queue set up between the API Server and the UI Server.

The idea is that you set up a message queue (using something like Amazon SQS or ActiveMQ or another STOMP compatible message queue). When your editors make changes to content, the API Server will drop a message onto the message queue to indicate what changed. The UI Server then picks up those messages and uses them to invalidate cached items within the UI Server.

ActiveMQ

Here is an example of setting up ActiveMQ:

CLOUDCMS_NOTIFICATIONS_ENABLED=true
CLOUDCMS_NOTIFICATIONS_STOMP_HOST=activemq
CLOUDCMS_NOTIFICATIONS_STOMP_PORT=61613
CLOUDCMS_NOTIFICATIONS_STOMP_USERNAME=
CLOUDCMS_NOTIFICATIONS_STOMP_PASSWORD=
CLOUDCMS_NOTIFICATIONS_STOMP_QUEUE_URL=/queue/cloudcms.ui.queue

You will need to first set up ActiveMQ and set up a Queue within the ActiveMQ config. For a reference of how this is done, we recommend taking a look at the Cloud CMS distributed Quickstart as it has ActiveMQ configured by default.

Amazon SQS

Here is an example of setting up Amazon SQS:

CLOUDCMS_NOTIFICATIONS_ENABLED=true
CLOUDCMS_NOTIFICATIONS_SQS_QUEUE_URL=http://sqs.us-east-1.amazonaws.com/{accountId}/{queueId}
CLOUDCMS_NOTIFICATIONS_SQS_REGION=us-east-1
CLOUDCMS_NOTIFICATIONS_SQS_ACCESS_KEY={accessKey}
CLOUDCMS_NOTIFICATIONS_SQS_SECRET_KEY={secretKey}

You will need to fill in the Queue URL, region and access/secret keys.

Timeout on Startup

Depending on your environment, you might choose to have the Cloud CMS UI Server wait a little bit before coming online. This is sometimes necessary to ensure that other containers have had sufficient time to come online.

One typical example is ActiveMQ. ActiveMQ takes a little while to start up and depending on how you've configured the startup order of your Docker containers, its possible for the UI Server to come online before the ActiveMQ container.

As a safeguard, we make available the option to have the UI Server wait a little while. You can configure this period using the following setting:

CLOUDCMS_STARTUP_TIMEOUT_MS=5000

Where the value provided is the time to wait in milliseconds. Thus, 5000 milliseconds as shown above prescribes a 5 second delay on startup.

Module Deployment

If you intend to allow developers to deploy modules to the Cloud CMS UI Server, you will need to inform the UI Server of the login information to use to access backend source control systems.

This is optional. If no credentials are supplied, the UI Server will attempt to pull down code anonymously. This will only work for public repositories. If you intend to deploy private repositories, the UI Server will need to be provided with credentials.

The UI Server supports GitHub and BitBucket.

To configure for GitHub, use the following to provide your credentials:

CLOUDCMS_NET_GITHUB_USERNAME=
CLOUDCMS_NET_GITHUB_PASSWORD=

To configure for BitBucket, use the following to provide your credentials:

CLOUDCMS_NET_BITBUCKET_USERNAME=
CLOUDCMS_NET_BITBUCKET_PASSWORD=

You can optionally configure the number of login attempts allowed for a given user before locking them out of the ui, and how long before they will be allowed back in. These should be configured to the same values used by the API). The time configured should be in milliseconds. The default number of allowed attempts is 3, the default reset timeout is 900000 (15 minutes), and login attempts check is true by default

CLOUDCMS_ATTEMPTED_LOGIN_CHECK_ENABLED=
CLOUDCMS_ATTEMPTED_LOGIN_CHECK_MAX_ATTEMPTS=
CLOUDCMS_ATTEMPTED_LOGIN_CHECK_RESET_TIMEOUT=