API Server

The Cloud CMS API Server is a Java application that launches inside of a Java Servlet Container. The Java application surfaces a REST API as well as backend services and DAOs to support connectivity to Mongo DB, Elastic Search and a slew of Amazon services including S3, SNS, SQS, Route 53, Cloud Front and more.

Properties File

Cloud CMS is primarily configured via a properties file that is auto-detected and loaded when the underlying Spring Framework starts up. This properties file is typically named docker.properties. The file should be loaded from the classpath root (and is typically bootstrapped from a classes directory).

For the most part, this properties file consists of key=value pairs that are static in nature. This key has that value and so on. Values may be strings, numbers and boolean (true/false). You do not need to wrap strings in quotes. Cloud CMS will handle the conversion for you.

In addition, you may wish to pull in environment variables from your Docker container OS. This is useful if you're launching Docker in AWS (or similar) and wish to store sensitive values (such as passwords, access keys, etc) outside of the docker.properties config file. Not only that, but it potentially allows your single Docker configuration to more easily reused across environments (by just changing environment variables).

To pull in environment variables, use the ${VARIABLE} value. For example,


For information on AWS, keep on reading. This is just an example.

XML File

The Cloud CMS API is a Spring MVC application that leverages Spring Security, Spring Transactions and a lot of other really good services to provide secure and fast request processing. As such, all extensions of the underlying services is done via Spring Bean configuration.

To make this easily extensible for customers, Cloud CMS uses an XML configuration file to let you override and configure beans. For the most part, you won't have to do this as most of the customizations are doing via the .properties file above.

However, there may be times that you wish to really modify how the API behaves by wiring in your own beans. We recommend doing this in a cloudcms-distribution-context.xml file. This file should be located in the classes/gitana/distributions directory.

The file should essentially look like this:

<?xml version="1.0" encoding="UTF-8"?>

    <!-- insert your customizations here -->


This file is optional but it may be referenced in some of the sections below.

Admin User Password

One of the first things you'll usually want to configure is the admin user's password. The admin user is created when you first start up Cloud CMS. You can set the password like this:


The admin password will be enforced to this value and cannot be accessed or changed at runtime. When you restart the API, the admin password will be reset to the value provided.

Note that we're storing the password in plaintext here. That's often fine for development and testing. But in production, you will generally prefer to take advantage of property encryption to protect your password.

If you use property-level encryption, you will provide the setting more or less like this:


The encrypted value is generated using a public key and can only be read by the Cloud CMS API server itself. You are free to use encryption with any properties that you wish.

Concurrent Request Rate Limits

You can limit concurrent requests on a per-tenant and per-user basis within Cloud CMS. This keeps track of how many HTTP requests are "in-flight" at any given moment. When the number of "in-flight" or concurrent requests exceeds the specified amount, an HTTP 429 status code is returned.

From a web architecture viewpoint, a 429 is a valid status code response and client code that calls into Cloud CMS is expected to handle this gracefully.

To specify rate limits per-tenant, use the following:


To specify rate limits per-user, use the following:



The Cloud CMS auditing service tracks every operation against auditable objects within the system and writes those operations to a special Audit collection. This Audit collection provides a reliable capture of what users did within your system and records every method invocation, including:

  • the method invoked
  • arguments passed to the method
  • the value returned from the method
  • the invoker of the method
  • when the method was invoked
  • exceptions that were raised

To enable auditing:



The API uses Log4j2 as its logging engine and provides a configuration-based way for you to customize the logging of various sub-services within the product. Each logger within the product logs at a given log level. You can increase and/or reduce the amount logging for each logger by adjusting its respective log level.

Custom Log Levels

To customize the log levels, add a log4j2-docker.xml file to the classpath. This file should sit at the root of the classpath. If you're unfamiliar with how to mount this into Docker, take a look at the quickstart example provided in the Cloud CMS Docker distribution. It provides a sample log4j2-docker.xml file with blocks of configuration that you can easily comment out to get started quickly with debugging.

The log4j2-docker.xml file provides a way for you to specify the Log4j2 log level for individual service beans or entire packages of services at once.

By default, the log levels within Cloud CMS are pretty conservative and are optimized for production usage. However, if you're running Cloud CMS in development or would like to get more log information to diagnose a problem, you can adjust the log4j2-docker.xml configuration to provide the level of granularity that you seek. Often, this involves adjust log levels from INFO to DEBUG.

Note that DEBUG should only be used while debugging or in development. We do not recommend running Cloud CMS with DEBUG logging in place on production. It will produce far too many logs and will also run more slowly.

Let's say you wanted to enable more logging for the rules engine within the product. You could do that with a log4j2-docker.xml file like this:

<?xml version="1.0" encoding="UTF-8"?>

        <!-- Set all classes in the org.gitana.platform.services.rule package to log with DEBUG -->
        <Logger name="org.gitana.platform.services.rule" level="DEBUG"/>


Log Outputs (stdout / stderr)

Several log files are maintained by the API server Java application. These can be accessed by exposing the log folder as a "volume" on the API server's docker container. Update the docker-compose.yml config file so that the folder: /opt/tomcat/logs is available to the docker host system.

This example mounts the logs folder to a host folder named "api-logs":

    build: ./api
        - cloudcms
        - mongodb
        - elasticsearch
        - ./api/api.env
        - "8080:8080"
        - ./api-logs:/opt/tomcat/logs

After running a new build (docker-compose build --force-rm) the folder will be created and the log files will be visible to the host.

The default server logging goes to cloudcms.log.

If you require logging of each API call to the API server you can monitor the Tomcat access logs: localhost_access_log.*.txt

Access Logs

Every request and response that the API processes is logged into its own Log4j2 appender. You can customize this appender to have those entries write to a different location, format differently, rollover to disk or even roll over to S3 periodically.

By default, the access logs appender (named RequestFile) is defined like this:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="info" packages="org.gitana.platform.services.log">
        <Property name="baseDir">logs</Property>
        <RollingFile name="RequestFile" fileName="${baseDir}/cloudcms-requests.log" filePattern="${baseDir}/cloudcms-requests/cloudcms-requests-%d{yyyy-MM-dd-HH-mm}-%i.log" append="false">
                <TimeBasedTriggeringPolicy interval="30"/>
                <SizeBasedTriggeringPolicy size="256 MB"/>
            <DefaultRolloverStrategy max="20"/>

You can override these settings via the same process as described above in which you add your own log4j2-docker.xml file. This file will be picked up by Cloud CMS and its settings will be merged into an overall Log4j2 configuration set. Specifically, you can redeclare the RequestFile RollingFile implementation and Cloud CMS will let your implementation override the one provided out-of-the-box.

Upon making changes, make sure you to rebuild the API docker container (docker-compose build --force-rm) and restart.

You should now see JSON objects describing API calls written to the logs folder as cloudcms-requests.log.

S3 Rollover

Cloud CMS includes an S3RolloverStrategy implementation that you can use to have your access logs rollover to S3 (in addition to rolling over on disk). This provides a convenient way to get your access logs off the server. And if you're running in a cluster, this provides a way to get your logs all collected into a single place.

To use this strategy, you simply need to add it to your RollingFile appender. This strategy takes a few arguments:

  • accessKey: the AWS account access key
  • secretKey: the AWS account secret key
  • region: the S3 region
  • bucket: the S3 bucket name
  • prefix: a prefix to append ahead of any created keys (such as cloudcms/production)

You can use a Properties block to accomplish this elegantly as shown in the code below:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="info" packages="org.gitana.platform.services.log">
        <Property name="REQUESTS_S3_ACCESS_KEY"></Property>
        <Property name="REQUESTS_S3_SECRET_KEY"></Property>
        <Property name="REQUESTS_S3_REGION">us-east-1</Property>
        <Property name="REQUESTS_S3_BUCKET"></Property>
        <Property name="REQUESTS_S3_PREFIX">cloudcms/production</Property>
        <RollingFile name="RequestFile" fileName="${baseDir}/cloudcms-requests.log" filePattern="${baseDir}/cloudcms-requests/cloudcms-requests-%d{yyyy-MM-dd-HH-mm}-%i.log">
                <TimeBasedTriggeringPolicy interval="30"/>
                <SizeBasedTriggeringPolicy size="10M"/>
            <S3RolloverStrategy accessKey="${REQUESTS_S3_ACCESS_KEY}" secretKey="${REQUESTS_S3_SECRET_KEY}" region="${REQUESTS_S3_REGION}" bucket="${REQUESTS_S3_BUCKET}" prefix="${REQUESTS_S3_PREFIX}" />

API Pagination

By default, any API calls that support pagination will be given a paginated limit of 25. In other words, if your API call doesn't specify how many records it wants back, it will get back 25 records at most. Cloud CMS does this to help protect against code that errantly forgets to include pagination in cases where you have very large record sets. Very large record sets implies lots of time to execute, lots of memory consumed and so on.


Be on the safe side and specify a limit in your paginated calls.

In addition, Cloud CMS will enforce a maximum pagination limit of 1000. If you try to retrieve more than 1000 records in a result set, your result will be capped. We cap this at 1000 by default though you're free to change this in your own Docker installations to suit your needs:


If you need to retrieve more than 1000 results, we recommend making multiple calls to paginate through the total set using the limit and skip options. See our documentation on Pagination.


Each API server that spins up supports clustering. When an API server comes online, it searches for other API servers that might be out there and part of the same cluster. If it finds any, it connects to them and redistributes any cache state to balance out the cluster.

Similarly, if a Cloud CMS API server goes offline, the other servers in the cluster become aware and re-balance as needed. In this way, a Cloud CMS API cluster is an ephemeral thing - servers may join and leave the cluster as demand increases or falls away.

Every API server, regardless of whether you intend it to participate in a multi-server cluster or not, requires that you provide a cluster.group.name and a cluster.group.password:


You can set these to anything you like. However, if you do intend to have other API servers join the cluster, they will also need to specify the same cluster.group.name and cluster.group.password.

When Cloud CMS starts up, it will bind a port that it will use to communicate with other cluster members (should they come along). As mentioned, even if your cluster is just size 1, you will need to bind this port.


The default port is 5800 if you don't otherwise specify it. This means that any other API servers can communicate with this API server instance on port 5800.

Cloud CMS will assume the IP address of the first network interface it spots. In most cases, this will resolve to localhost or for development or simple server configurations. For more complex configurations where you may have multiple network interfaces, you can specify which interface(s) should be considered via the following configuration:


The cluster.interfaces.interface property can either be the IP address of the interface or a comma-delimited value of multiple interfaces to consider in order.

Note that the use of interfaces applies most specifically when using multicast or tcpip discovery providers. For other provider types, such as aws or zookeeper, you will likely not need to bother with this.

In cloud deployment scenarios, where containers are distributed across multiple hosts (and across availability zones), you will need to provide a publicly accessible IP address per server instance. This public-address is an IP address which other Cloud CMS API Servers can use to connect to -this- API server.


The public address identifies the public IP address of the box as seen by the outside world. If you have two EC2 instances, with IP addresses and, each box will have a slightly different configuration with cluster.public-address= for the first box and cluster.public-address= for the second.

Suppose box #1 comes online first. It will bind to Now suppose that box #2 comes online. It will bind to If configured properly, it will then call out to try to find other boxes that are members of the same cluster. It will find the first box and connect to it on

Thus, the public address is important as it establishes an IP address that the outside world can use to connect to your API server. This IP address must be publicly accessible.

If you're configuring this and get stuck, use Telnet to make sure that your cluster port can be connected to. It must be available from one API server to the other.

Note that the public-address property is typically required for aws, zookeeper and other dynamic and cloud-friendly deployment scenarios.

By default, Cloud CMS will perform the handshake described above. If it can't find something on 5800, it'll make another attempt at 5801. Then 5802 and so on. It will try three times and if nothing works, it'll consider things to have failed. This feature is provided to make it easier to have things work in cases where there are minor port conflicts or multiple API containers running on a single host.


Note that port auto incrementing is enabled by default.

Cloud CMS's clustering and discovery of other API servers runs automatically at startup. It then remains active throughout the lifetime of the server. As other servers come and go, your API server will log messages to indicate that it has discovered a new member or that a member left.

By default, Cloud CMS will wait 10 seconds upon startup to "allow things to settle". For low latency or typical environments, this is more than sufficient. However, for slow network scenarios, you may wish to increase this.


Cluster Discovery

When Cloud CMS servers are brought online, they discover one another and then get on about business. The exact strategy used to discover one another is configurable. The following discovery services are available:

  • Multicast
  • TCP/IP
  • Amazon Web Services
  • ZooKeeper

By default, the Cloud CMS API server is configured to use Multicast. This means that will work out-of-the-box for scenarios where containers are launched against the host's network (such as when Docker is launched with -Dnet=host`).

However, for cases where containers are launched on their own network or launched as part of a Docker Machine running on a cloud provider (such as EC2), you will need to use a different discovery mechanism.

Interface Configuration

Depending on how Docker is set up, you may have multiple network interfaces defined. For example, if we bash into the container running the API, we can run:

ip address

And we may see something like:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet scope host lo
       valid_lft forever preferred_lft forever
2: tunl0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN group default qlen 1
    link/ipip brd
3: ip6tnl0@NONE: <NOARP> mtu 1452 qdisc noop state DOWN group default qlen 1
    link/tunnel6 :: brd ::
121: eth0@if122: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default 
    link/ether 02:42:ac:13:00:05 brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet brd scope

This indicates that there are multiple network addresses set up. In this case, when Cloud CMS starts up, it will make a best guess about which network interface to bind to. This isn't ideal because while Cloud CMS is very clever and will make a good guess, it may still get this wrong.

For example, from the list above, Cloud CMS might thoughtfully choose That's the first one. And if the Docker containers were running in host mode, this could work. However, if you're running Docker in bridge mode (which is the mode that most of the Cloud CMS quickstart kits ship with), then this will result in a situation where each cluster member is bound to a loopback address which won't let them see each other.

To resolve this, we want to make sure that the cluster members bind to the address. That's for this specific case. We won't know the precise IP address of course, since Docker assigns those dynamically, but we do know that it will be a wild card value essentially matching 172.*.*.*.

Thus, we may opt to adjust the docker.properties file to include:


That way, when the API servers start up, they'll bind to their respective 172.*.*.* address and will be able to see each other.

Discovery Services

The following Discovery Services are available:


Cloud CMS supports multicast for scenarios where containers are deployed to the same network as the host. In this case, everything (host and containers) are bound under the same network interface and multicast can be used as a communication mechanism between the Cloud CMS API servers.

Multicast is typically very good for development servers or even test servers that run on top of a simplified or common network configuration. When Docker is launched with the -Dnet=host option, the network used by the containers is the same as that of the host and multicast applies.


In anything that is production grade (such as cloud deployments), you will typically have your containers running is isolated network environments and so multicast will simply not work.

Suppose, for example, that you have multiple API servers defined in your Docker setup. With multicast, you don't have worry about how many -- they can all use the same configuration. We might set it up like this:



Note that we're forcing both servers to look to the 172.*.*.* network interface (instead of the loopback). Please see the section above on interfaces for more information. By providing an explicit interface, we remove the possibility of Cloud CMS auto-configuring for the wrong network interface.


Cloud CMS provides a way for you to name all of the servers explicitly that are participating in your cluster. The members field in the tcpip config lets you explicitly spell out the <ip>:<port> network reachable addresses for the API server.

In this way, if you wish to have no dynamic or automatic discovery at all, you can use tcpip discovery to spell out all participants from the beginning.


In general, you should think of tcpip discovery mode as a fallback if nothing else works. Running in tcpip mode trades off any dynamic detection of servers except for those that start up on the given list of IP addresses. This can be good for some scenarios but for most "cloudy" deployments, you will want to use a different discovery services such as aws or zookeeper.

Suppose, for example, that you have two API servers defined in your Docker setup. One container might be called api1 and the other might be called api2. These containers, if running on the same host, might have ports mapped for 5801 and 5802 respectively.

The cluster could be configured using TCP/IP like this:



Note that we're forcing both servers to look to the 172.*.*.* network interface (instead of the loopback). Please see the section above on interfaces for more information. By providing an explicit interface, we remove the possibility of Cloud CMS auto-configuring for the wrong network interface.

Amazon Web Services

If you're running your containers on Amazon AWS (EC2), then you will likely want to take advantage of the aws discovery service. To use this service, just provide the following:


When your API server starts up, it connects to Amazon's API to find other EC2 instances that came online and were running API servers for the same cluster group and password. It then auto-configures for the public IP addresses and ports of those API servers.

This is a very nice and efficient mechanism for discovery. It gives you the advantages of elastic instances (you can add and remove instances on the go) and avoids the need to detect and wire in IP addresses ahead of time.

The required properties are:


You must also specify either an access/secret key pair (cluster.aws.accessKey and cluster.aws.secretKey) or an IAM role (cluster.aws.iamrole).

All other properties are optional:

  • cluster.aws.timeout.seconds specifies the maximum amount of time to wait for a member of the cluster to discover another member of the cluster.

By default, the EC2 discovery process looks across all of the EC2 instances in your region. It connects to each one and tries to authenticate using the cluster group name and password. If the EC2 instance doesn't respond or the cluster parameters do not match, the EC2 instance is filtered out. The remaining set after filtering comprises the cluster members.

For efficiency purposes, you can improve this lookup process by filtering. You can filter either on tags or security groups:

  • cluster.aws.tag.key and cluster.aws.tag.value filters to only consider EC2 instances with a matching tag key/value pair.
  • cluster.aws.securitygroup filters to only include EC2 instances in a given security group.
Public Address

There are several ways to launch Cloud CMS within AWS. These may include: the AWS Docker Engine for Docker Machine, Amazon's Elastic Container Service, Amazon Elastic Beanstalk or perhaps another way. Depending on how you launch, you'll end up with Docker containers running in a network environment over which you will have some degree of control.

The ideal scenario is one where the networking environment is running in host mode so that the container's networking environment is shared with the host. In this configuration, the default network interface is usually the public interface. The clustering mechanism usually picks up the right "public" IP address in this scenario.

However, in some environments (such as when using multiple container Elastic Beanstalk Dockerrun.aws.json files to launch), you'll simply be given a network environment. These may be bridged environments with multiple interfaces. In these scenarios, it isn't always possible for the clustering mechanism to pick out the right public IP address.

Furthermore, AWS maintains the notion of "public" IP addresses vs. "private" IP addresses for your EC2 instances. In most cases, what you're looking to use is the "private" IP address and the clustering mechanism out to be able to pick it out for you.

However, at times when it cannot, you may need to set the cluster.public-address property to nudge things along. This property tells your container how to identify itself to other members in the cluster. Suppose you have Container A and Container B. Container B starts up and calls out to Container A to see if it is a member of the cluster. Container A must reply with a "public address" that matches what Container B expects. For simple networking configurations, this is trivial and automatic. However, if you have multiple interfaces, it is possible for Container B to pick the wrong interface and thus the wrong IP address in response.

In these scenarios, you can force the public address to the private IP of your EC2 instance like this:


If you want to force to the public IP, you can do so like this:

Configuring for EC2 or ECS

In order for EC2 Discovery to work within an AWS EC2 or ECS Cluster, you will need to accomplish the following:

  1. Ensure that your API docker container starts up in host mode (not bridge)
  2. Ensure that the API selects the correct network interface when it starts up.

When using ECS, make sure that your taskdef.json file starts the container in host mode by setting the following:

"networkMode": "host"

If you're launching in docker-compose, you can adjust your docker-compose.yml file to feature something like this:


    build: ./api
    network_mode: host
      - ./api/api.env
      - "80:8080"
      - "5800:5800"

If you're launching using the docker command, make sure to pass --network=host as an argument to make sure the container launches with host networking.

Adjust your docker.properties file to make sure Cloud CMS binds to the correct interface, like this:


Please note that the 10.0.*.* value depends on your CIDR block definition. If more than one subnet or custom VPC is used for cluster, it should be checked that container instances within the cluster have network connectivity or have tracepath to each other.


If you're running your containers in the cloud and are either not running on AWS or elect not to use AWS EC2 Discovery Services for any reason, then you may choose to use ZooKeeper as an alternative.

Apache ZooKeeper provides a directory service whereby Cloud CMS API Servers register themselves as they come online. When additional services come online, they discover previous servers and so on.

The following properties must be set:


In effect, ZooKeeper provides the same mechanism as AWS Discovery Services but will work for any cloud provider. The only caveat is that you must run ZooKeeper yourself as part of your environment so that any API servers running can connect and utilize it as a service.

Binary Storage

Cloud CMS lets you configure one or more back-end Binary Storage providers that the system will use to persist and retrieve binary files for a given datastore. Binary Storage providers are sensitive to datastore scoped configurations allowing tenants to customize storage on a per-datastore, per-project and per-platform basis.

At its core, Binary Storage providers are configured at the Spring bean level. You can define as many Binary Storage providers as you wish. Each Binary Storage provider instance is a singleton that plays the role of manufacturing Binary Storage instances when requested by upstream services. The provider framework takes on responsibility for caching storage instances where appropriate.

Binary Storage providers are used to binary files and attachments where needed in the product. Attachments to content nodes, for example, are stored via a Binary Storage provider. As are images attached to principals, archives, projects and more.

By default, Cloud CMS has several providers wired for you out-of-the-box so as make it simple to set up global binary persistence to a single location. This is the most common use case and it also doesn't preclude further configuration and customization later.

The following Binary Storage provider types are available out-of-the-box:

  • mongodb
  • file
  • AWS_S3
  • caching
  • fallback
  • s3gridfs

To configure the global Binary Storage provider, set the following property to one of the values above:


If not otherwise specified, the default is to use a provider type of mongodb (which is for GridFS).

Mongo DB (Grid FS) provider

This provider is configured by default and will be used if you don't override the global setting.

GridFS is a "file system" implementation that is provided by Mongo DB whereby binary files are written into Mongo DB. The advantage here is that your files will reside in Mongo DB (keeping everything in one place) and will enjoy all of the replica set and shard architecture advantages that Mongo DB affords. Furthermore, GridFS is low latency and works nicely in a clustered or distributed setting where all servers in the cluster can fall back on it as a single source of the truth.

One downside with GridFS is that, since everything goes into MongoDB, your MongoDB data partitions and volumes need to grow to accommodate the total storage size of the binary files. If you start putting really big binary files into Cloud CMS, your MongoDB storage requirements will increase likewise. This can have cost implications and may introduce some challenges from a DevOps perspective in terms of managing EBS volumes and the like.

GridFS is a good solution if your total binary file size is predictable and manageable.

To enable the mongodb GridFS as the global Binary Storage provider, set the following:


File System provider

For non-clustered environments where you only have a single Cloud CMS API server, the file system Binary Storage provider is available and will let you store all of your binary files on local disk. This is ideal for development boxes.

This provider is not distributed or cluster-aware. It cannot be used in clustered API deployments in any capacity since each server in the cluster is essentially managing its own local store.

To enable the file system as the global Binary Storage provider, set the following:


You must also specify the storagePath where files are to be written:


This directory must exist and the API process must have sufficient read/write privileges to the directory.

Amazon S3 provider

Cloud CMS can be configured to write and read binary files from Amazon S3 directly. This enables your API cluster to use Amazon's scalable S3 storage without concern for growth in local disk volumes. Since each server in the cluster communicates to S3 and uses S3 as a common resource, this Binary Storage provider implementation is cluster-safe and ready to go.

To enable the AWS_S3 backend as the global Binary Storage provider, set the following:


You must then specify the Amazon API keys to use and any additional properties for the S3 connection pool:


One downside to using S3 directly is latency. Since every binary operation requires a network connection back to S3, latency will eventually prove to be an issue. Fortunately, Cloud CMS provides per-server local caching for optimized performance. Read on to learn more about this.

Caching provider

A caching provider lets you add cluster-aware caching to any other provider. It wraps an existing provider with caching so that binary files are written to local disk and served back from local disk whenever possible. As assets are updated, local disk cache is maintained and purged as needed across the cluster.


You must set up caching like this:


In this example, the caching provider is set up to wrap around the AWS_S3 provider to offer cluster-aware, disk-based caching. Binary files are written to disk at /data/cms/binaries.

If cachePath is not provided, a temp directory path will be used (and cached disk state will not survive server restarts).

Fallback provider

The fallback Binary Storage provider provides a safe way to layer a "master" provider on top of another (or several others) with the objective of gradually migrating binary dependencies from the other providers to the master. The fallback Binary Storage provider takes a list of providers and binds them together into this configuration.

The first provider in the list is the "master" provider. The master provider is the preferred provider.

  • When binary files are read, the master provider is consulted first. If the file isn't found there, the other providers are consulted in turn. If none of the providers have the file, a 404 is returned. If any of the providers have the file, it is streamed back.
  • When binary files are created or updated, the master provider receives the file.
  • When binary files are deleted, they are deleted from ALL providers.

This is ideal for situations where you may have data already existing in one provider (GridFS) and want to transition to using another provider (S3). In this case, you'd set S3 as the primary provider and GridFS as the other provider in the list. Binary data that cannot be found in S3 will fallback to being served from GridFS. However, any new binary data going forward will be written solely to S3.

To enable the fallback provider as the global Binary Storage provider, set the following:


And then configure the provider like this:


S3 with Grid FS fallback and file caching

A specific provider is offered out-of-the-box to support S3 with file caching turned on. It further supports GridFS as a fallback in case binary content pre-existed therein.


You must then configure the provider like this:


If cachePath is not provided, a temp directory path will be used. Note that a temp directory means that the local disk cache (per server) will not survive server restarts. First requests for binary assets to newly started servers will pull down from S3 and begin rebuilding the cache anew.

We recommend using s3gridfs in production and as a simplified means of configuring S3 in production clusters.

One additional requirement for the s3gridfs provider is that you register a custom Spring bean that defines the S3 settings. This is done by adding some XML to the cloudcms-distribution-context.xml file. The custom bean should look like this:

<util:map id="defaultBinaryStorageConfiguration">
    <entry key="accessKey" value=""/>
    <entry key="secretKey" value=""/>
    <entry key="bucketName" value=""/>
    <entry key="region" value=""/>

You will need to fill in the values for accessKey, secretKey and bucketName. You can simply drop in these values or you may opt to draw these from the docker.properties file.

For example, you could set the XML to:

<util:map id="defaultBinaryStorageConfiguration">
    <entry key="accessKey" value="${custom.accessKey}"/>
    <entry key="secretKey" value="${custom.secretKey}"/>
    <entry key="bucketName" value="${custom.bucketName}"/>
    <entry key="region" value="${custom.region}"/>

And then add the following to your docker.properties file:


Now just plug in your accessKey, secretKey, bucketName and region to your docker.properties file.

Mongo DB

Mongo DB provides the primary data store for Cloud CMS. Cloud CMS creates a connection pool that it uses to communicate with Mongo DB while Cloud CMS is in service. You can configure Cloud CMS to connect to Mongo DB running either as a Docker container or as a standalone service.

In addition, you can configure Cloud CMS to connect to Mongo DB running as a standalone services, in a replica set or in a sharded configuration.


Use the mongodb.hosts setting to specify a comma-delimited set of <server>:<host> entries. Each entry should be the network-accessible address of either a mongod (in the case of a standalone or replica set configuration) or mongos process (in the case of a sharded configuration).

To connect to a single mongod or mongos process, you might use:


Or connect to a multiple servers in a replica set:


Cloud CMS will initialize the MongoDB driver connection and manage that connection to best take advantage of what was supplied. If you supplied a list of replicas, for example, Cloud CMS will automatically migrate between members of the replica set on failure or when you switch primary.


By default, Cloud CMS assumes that connectivity to Mongo DB is unauthenticated. In other words, it assumes that Mongo DB has been configured in such a way as to not require authentication.

This is generally acceptable for development. But for production environments, you will want to make sure that Mongo DB is configured for authentication, that a user exists in Mongo DB with sufficient access privileges and that you supply the username and password of that user like this:



By default, Cloud CMS assumes that connectivity to Mongo DB does not use SSL. If you wish to enable SSL, then set the following properties:


Grid FS

By default, Cloud CMS will store binary files into Mongo DB's Grid FS storage system. This is specified via the following configuration option:


You can use setting to change to a different storage provider or activate a custom implementation that you've built.


Mongo DB has an interesting "feature" (which some might argue is a bug and others religiously would defend that it isn't) in that count()` operations against collections take O(n) time. This means that the amount of time needed to count rows in a collection will increase as the collection size increases.

This opens up a downside in that a request could come along and perform a count() and therefore take an unpredictable amount of time. To defend against this, Cloud CMS lets you specify the maximum amount of time you wish a count()` operation to execute before it is forced to fail. A forced fail means that the operation fails, the database cursor is released, memory is cleaned up and the API server nicely releases any resources it might be holding on to.


In addition, you may opt to limit the maximum number of items to count. This is an alternative to defaultMaxCountTimeMs in that you can lock down the maximum count size, letting you be sure that things can't get out of hand. This makes your request calls more predictable but also means that your total record set size may be inaccurate for large counts.


An example - suppose defaultMaxCountTimeMs were set to 10 seconds and there were 10 million items in a collection. If you ran a count() and it took 11 seconds to execute, an exception would be raised and the operation would fail. You could raise defaultMaxCountTimeMs to 11 seconds and then things would work (but the operation would still take 11 seconds to complete).

But what if you really didn't care about whether the results had 10 million items or 1000 items. Your end users aren't going to paginate through 10 million entries are they? (or maybe they are... hmmm... it is your call)

Still, suppose we knew they'd never do that. Perhaps our UI front end doesn't even provide pagination or we have some other kind of UI control which is far more intuitive. Anyway, in that case, we could set defaultMaxCount to 1000.

Now when the count() operation occurs, it will be extremely fast. And the reason is because it takes a lot less time to return the first 1000 results than the first 10 million.


Another potentially expensive operation in Mongo DB is a find(). An end user could run a query that runs for a very long time. While the query is running, the Mongo DB database connection is consumed, a thread is hung in the API server and the end user is waiting.

In general, when building scalable and fail-fast applications, we'd rather nip this in the bud. To do so, we can limit the maximum amount of time a find() operation can run like this:


Now, if the find() operation runs for more than the prescribed amount of time, an exception is raised, the operation fails and the resources released. Nice and clean.

Slow Queries

While developing your front-end applications, you'll occasionally experience slow queries that build up as you put in more and more content. These queries are usually slow because they haven't been indexed. Cloud CMS lets you add custom indexing to branches and so you'll want to do that.

To help you along, Cloud CMS offers the ability to log slow queries to its log file. This is corollary to the tenant log file that you already find in Cloud CMS, however it will be available to your developers and administration team.


This will produce a lot of explanations and so we only recommend this on development or non-production environments.

Write Concern

By default, the Write Concern for MongoDB is set to ACKNOWLEDGED. This means that any writes to the MongoDB database will wait for acknowledgement from the DB before proceeding. This is a relatively safe way to run as it ensures that MongoDB is aware of any any data that was committed and puts MongoDB in a position where has the opportunity to control the situation from a disaster recovery perspective.

That said, you may wish to change the Write Concern to make it more robust. The JOURNALED setting, for example, tells Cloud CMS to wait for MongoDB to acknowledge that the data was written to its journal before continuing. This takes a little longer but ensures that MongoDB can fully recover from its own journal via a repair or on next startup.

If you are running a replica set, then the W1, W2 and W3 tell Cloud CMS to wait until the data was successfully written to 1, 2 or 3 members of the replica set respectively. You may also choose to set this to MAJORITY to tell Cloud CMS to wait until the majority of replica set members commit the data before proceeding.

With replica sets, it is important to understand that the primary (W1) must be committed and the other members are eventually consistent by default. You may choose to set the non-primaries as slaveOk (done within MongoDB) to support reads from non-primary members. However, if you do this, you will need to make sure that the WriteConcern configured here enforces consistency across the non-primary members on commit (in other words, the data should be written across all members or none on each commit).

To adjust the write concern, use the following setting:


Elastic Search provides a secondary index of searchable content for Cloud CMS. It provides full-text search and structured query against it from within Cloud CMS using the Elastic Search DSL.

When content is written into Cloud CMS, it is primarily written into Mongo DB. It then secondarily written into Elastic Search. As content is created, updated and deleted, Elastic Search has its indexes kept perfectly in sync so that text-based search is available against every branch in a repository.

Elastic Search runs as a separate service from the API server. Each API server, upon starting up, creates a connection pool to your Elastic Search endpoint that it uses to communicate, execute queries and maintain its search indexes in real time.

Cloud CMS supports Elastic Search clustering. It only needs to know the IP address of one member of the cluster and the cluster name to connect.

The configuration properties are specified like this:


Where hosts is a comma-delimited set of <host>:<port> or simply <host> entries.

Email Provider

Cloud CMS allows you to configure an email provider that will be used to send email to people that you invite to participate in your project. The default email provider is used to dispatch those invitations and is also used to send emails during a coordinated registration process.

To set your email provider, use the following properties:


Job Dispatcher

Each API server that spins up supports 2 primary functions. The first is to handle incoming web requests and turn them around quickly. The second is to process background jobs that are queued up in the distributed job queue. Background jobs typically include content indexing, exporting and complex mimetype conversions or data extractions.

These kinds of jobs "take a while" and so they're frequently moved off the request and placed in the asynchronous job queue. Every server in the cluster (or in an API worker cluster) that is configured to process jobs will work together to coordinate the distribution of job work by all cluster members.

By default, every API server performs both functions (web request handler and job worker). However, you can control this behavior via the following flag:


For more advanced and scalable deployments of Cloud CMS, you will want to run two tiers of API servers -- one tier for handling web requests and the other for working on background jobs. That way, any long-running intensive work won't steal CPU cycles from your web request handling. You can use the flag above to achieve this by enabling the job dispatcher only for the API servers in the job worker tier.

Any servers running the job dispatcher can configure the maximum number of jobs using this setting:


You can also configure the maximum number of jobs that the job dispatcher will dispatcher per tenant platform:


If you're running a multi-tenant offering, you can use this to ensure that no single tenant may draw too much job handling. If you're running single tenant, you may disable this by setting:


In addition, individual job workers can be turned on and off. This allows you to segment your API workers so that you can allocate job workers to certain servers (so that heavier tasks can be allocated to higher powered servers and so on).

Here's an example of some of the jobs offered being enabled:


Web Shot

Cloud CMS features the ability to take snapshots of web pages and other HTTP resources. Most of this integrated into the product automatically. The Cloud CMS analytics engine, for example, captures snapshots automatically for pages whose interaction is being reported upon.

The Cloud CMS Web Shot server provides the ability to capture these snapshots. The Cloud CMS API calls out to this server when needed.

This setting is optional. If provided, Cloud CMS will capture snapshots for your assets.

To configure the location of the Cloud CMS Web Shot server, use this property:


Backdoor Authentication

At times, you will want to configure a secret 'backdoor' password that allows you to log in or impersonate any user in your platform. You can do so by enabling backdoor authentication and specifying a password like this:


Field Encryption

Cloud CMS generates a salt value that is used to encrypt fields such as password fields or credential keys and secrets. This salt value takes a number of inputs -- one of which is the a secret key that you can provide like this:

org.gitana.platform.services.encryption.secret=<anything you like>

Ticket Encryption

Cloud CMS writes back a GITANA_TICKET cookie with every API request. The ticket provides a cookie-based way to store the access token that is required for every request to the Cloud CMS API. In this way, the Cloud CMS API can be used to serve back assets directly to a browser where requests do not originate from a driver but instead of native HTML elements like IMG tags (with src attributes).

This GITANA_TICKET can be encrypted so that the access token is never out in the open. To encrypt the ticket, you simply need to provide an encryption secret for the ticket generator - liek this:



Cloud CMS retains deleted nodes in per-branch collections (known as "deletion" collections). The product provides services so that editorial teams can quickly restore deletions back to the originating branch in the event that something was deleted accidentally. The "deletions" collection (per-branch) provides a fast and efficient way to discover recent deletions and restore without a deep interrogation of the master node list.

Note that each branch's "deletions" collection is essentially a copy of the node made available to support query and recovery quickly. The actual master copy of the deleted node is always contained in the master node record. Cloud CMS is a copy-on-write system and so a master record of all nodes is always retained. In the end, your data is always recoverable.

That said, the facility of the deletions collection can be customized according to your editorial needs. Given that it tracks all deletions, the collection can grow to be quite large and so you may want to set automatic collection capping so that the total number of available deletions is limited in size over time.

To enable auto-capping, set the following properties, kind of like this:


The maxSize setting describes the maximum number of deleted records allowed before the collection is capped back to the resetSize. In this case, if the collection has 10000 deletion records in it and you delete just one more node, the deletion records will drop their oldest entries and the collection will resize to 7500.

Third Party / OS Libraries

The Cloud CMS API runs in an OS environment that has been configured and optimized to support its runtime needs. These include OS updates and third party installations of common libraries.



Provides Cloud CMS with services for mimetype transformation, extraction and more for image formats.




Provides Cloud CMS with video services including mimetype conversion, extraction and image manipulation of frames.




Provides Cloud CMS with support for OpenDoc and Microsoft Office Formats.


Clam AV Antivirus


Provides Cloud CMS with support for virus scanning and file quarantine on upload and storage.


GeoLite2 Database


Provides Cloud CMS with the ability to interpret latitude/longitude information. The database for GeoLite2 is included with the Cloud CMS API.




Web / HTTP

The API runs inside of a servlet container. You can adjust the server-side request-handling characteristics through the following properties.

Multipart File Handling

Set the maximum size (in bytes) of any multipart requests. This is the maximum size of the entire multipart request (as a summation of the sizes of all parts). This is set to 1GB by default.


Set the maximum size (in bytes) of any individual parts in the multipart request. This is set to 512MB by default.


Set the maximum size (in bytes) for a part that is allowed to reside in a memory buffer during multipart processing. This is set to 128KB by default.


Set the default encoding for any parts. This is set to the servlet spec ISO-8859-1 by default.


Notifications (UI Server)

The API can be configured to send notification messages to the UI Server and other endpoints when content is created, updated or deleted. These messages are delivered asynchronously and can be used to invalidate caches on external applications (among other things).

This section describes how to configure notifications between the Docker API container and the Docker UI container.

If you're looking for information on how to set up ad-hoc notifications between an Application instance and a custom application, see Configuring Amazon SNS.

Active MQ (UI Server)

To enable Active MQ between the API and the UI Server, add the following to your cloudcms-distribution-context.xml file:

<bean id="cloudcmsUIServerApplicationDeployer" class="org.gitana.platform.services.application.deployment.CloudCMSApplicationDeployer" parent="abstractApplicationDeployer">
    <property name="type"><value>${gitana.default.application.deployer.uiserver.type}</value></property>
    <property name="deploymentURL"><value>${gitana.default.application.deployer.uiserver.deploymentURL}</value></property>
    <property name="domain"><value>${gitana.default.application.deployer.uiserver.domain}</value></property>
    <property name="baseURL"><value>${gitana.default.application.deployer.uiserver.baseURL}</value></property>
    <property name="notificationsEnabled"><value>${gitana.default.application.deployer.uiserver.notifications.enabled}</value></property>
    <property name="notificationsProviderType"><value>${gitana.default.application.deployer.uiserver.notifications.providerType}</value></property>
    <property name="notificationsProviderConfiguration">
            <entry key="host"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.host}</value></entry>
            <entry key="port"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.port}</value></entry>
            <entry key="username"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.username}</value></entry>
            <entry key="password"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.password}</value></entry>
    <property name="notificationsTopic"><value>${gitana.default.application.deployer.uiserver.notifications.topic}</value></property>

And fill in the following to docker.properties to override the Active MQ settings:


Amazon SNS (UI Server)

To enable Amazon SNS between the API and the UI Server, add the following to your cloudcms-distribution-context.xml file:

<bean id="cloudcmsUIServerApplicationDeployer" class="org.gitana.platform.services.application.deployment.CloudCMSApplicationDeployer" parent="abstractApplicationDeployer">
    <property name="type"><value>${gitana.default.application.deployer.uiserver.type}</value></property>
    <property name="deploymentURL"><value>${gitana.default.application.deployer.uiserver.deploymentURL}</value></property>
    <property name="domain"><value>${gitana.default.application.deployer.uiserver.domain}</value></property>
    <property name="baseURL"><value>${gitana.default.application.deployer.uiserver.baseURL}</value></property>
    <property name="notificationsEnabled"><value>${gitana.default.application.deployer.uiserver.notifications.enabled}</value></property>
    <property name="notificationsProviderType"><value>${gitana.default.application.deployer.uiserver.notifications.providerType}</value></property>
    <property name="notificationsProviderConfiguration">
            <entry key="accessKey"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.accessKey}</value></entry>
            <entry key="secretKey"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.secretKey}</value></entry>
            <entry key="region"><value>${gitana.default.application.deployer.uiserver.notifications.configuration.region}</value></entry>
    <property name="notificationsTopic"><value>${gitana.default.application.deployer.uiserver.notifications.topic}</value></property>

And fill in the following to docker.properties to override the Amazon SNS settings:


Multifactor Authentication (MFA)

Cloud CMS lets you set up Multifactor Authentication (MFA) to provide better security for your users. With Multifactor Authentication configured, your users will have the option to receive a verification code on their mobile devices that is required for login. The helps ensure that hackers cannot solely gain access to your users' account credentials and use them to compromise your system.

Cloud CMS lets you configure Multifactor Authentication at runtime using a Service Descriptor from within your tenant. However, if you're setting up Cloud CMS via Docker, you also have the option to adjust default MFA bindings as well as configure how the admin user and backdoor passwords work with MFA accounts.

Define System Authenticators

For each provider type (such as Authy or Duo), there will typically be a Registrar object that you can use to quickly register a new system-defined Authenticator of that type.

For example, you might define an Authy authenticator with ID test like this:

<bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorRegistrar">
    <property name="id"><value>test</value></property>
    <property name="apiKey"><value>API_KEY</value></property>
    <property name="apiUrl"><value>API_URL</value></property>

Or a Duo authenticator with ID test like this:

<bean class="org.gitana.platform.services.authenticator.duo.DuoAuthenticatorRegistrar">
    <property name="id"><value>test</value></property>
    <property name="integrationKey"><value>INTEGRATION_KEY</value></property>
    <property name="secretKey"><value>SECRET_KEY</value></property>
    <property name="apiHost"><value>API_HOST</value></property>

These authenticator instances must then be bound to principals or behaviors as described below.

Configure MFA for Admin Account

You can lock down the admin account so that attempts to log in as admin will require multifactor authentication. To do so, use the BindAdminUserSystemAuthenticator bean.

Here is an example where we bind the admin account to a specific predefined Authy user with a given Authy ID.

<bean class="org.gitana.platform.services.authenticator.BindAdminUserSystemAuthenticator">
    <property name="bindingProperties">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorBindingPropertiesBeanFactory">
            <property name="authyId"><value>12345678</value></property>
    <property name="descriptor">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorDescriptorBeanFactory">
            <property name="id"><value>test</value></property>

Note that this makes use of the AuthyAuthenticatorBindingPropertiesBeanFactory and AuthyAuthenticatorDescriptorBeanFactory classes to make configuration easier.

And here is an example using the Duo provider:

<bean class="org.gitana.platform.services.authenticator.BindAdminUserSystemAuthenticator">
    <property name="bindingProperties">
        <bean class="org.gitana.platform.services.authenticator.duo.DuoAuthenticatorBindingPropertiesBeanFactory">
            <property name="userId"><value>DUO_USER_ID</value></property>                                           
            <property name="username"><value>DUO_USER_NAME</value></property>
    <property name="descriptor">
        <bean class="org.gitana.platform.services.authenticator.duo.DuoAuthenticatorDescriptorBeanFactory">
            <property name="id"><value>test</value></property>

This uses the DuoAuthenticatorBindingPropertiesBeanFactory and DuoAuthenticatorDescriptorBeanFactory classes to make configuration easier.

Configure MFA for a Principal

You can also bind an authenticator into place at the system level for any arbitrary principal provided that you know that principal's Domain ID and Principal ID.

Use the BindPrincipalSystemAuthenticator bean to achieve this.

Here is an example:

<bean class="org.gitana.platform.services.authenticator.BindPrincipalSystemAuthenticator">
    <property name="bindingProperties">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorBindingPropertiesBeanFactory">
            <property name="authyId"><value>12345678</value></property>
    <property name="descriptor">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorDescriptorBeanFactory">
            <property name="id"><value>test</value></property>

Configure MFA for backdoor password

You can also bind an authenticator in place for any user who attempts to log in using the backdoor password.

Use the BindBackdoorSystemAuthenticator bean to achieve this.

Here is an example:

<bean class="org.gitana.platform.services.authenticator.BindBackdoorSystemAuthenticator">
    <property name="bindingProperties">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorBindingPropertiesBeanFactory">
            <property name="authyId"><value>12345678</value></property>
    <property name="descriptor">
        <bean class="org.gitana.platform.services.authenticator.authy.AuthyAuthenticatorDescriptorBeanFactory">
            <property name="id"><value>test</value></property>