Connecting Remote Servers - Documentation topics on: environments,push environment,push publishing,receive from environment,remote publishing,send to environment,.

Connecting Remote Servers

The Publishing Environments tab displays a list of Send To Environments that your dotCMS server can publish content to, and the Receive From servers that your dotCMS server will accept content from.

Configuring Environments and Servers

  • You can have multiple Send To Environments, and you can group multiple Endpoint servers into each Environment. Each time you push content, you can choose which Environment(s) it is pushed to, which in turn determines which server or servers the content is pushed to.
  • You can have multiple Receive From servers, and any of them may push to your dotCMS server at any time (subject to push permissions and configuration on the sending server).
  • For any push to succeed, both the sending server and the receiving server must be properly configured:

Push Publishing Part One: Configuring Environments & Servers

Send To Environments

A push publishing Environment allows you to group one or more Endpoint servers to receive content pushed to the Environment. To create a new Environment, click the Add Environment button on the Publishing Environments tab.

A dialog box opens with the following fields:

ParameterDescription
Environment NameThe name of the Environment. Displayed and selected when users push content.
Who Can Send to this EnvSpecifies push Permissions, defining which Users and/or Roles are allowed to Push content to this Environment.
Push ModeSpecifies whether content pushed to this Environment is pushed to just one Server configured in the Environment or all of them.
  • If Push to One Endpoint is selected and the Environment has multiple Endpoints configured, dotCMS will randomly pick one of the servers in the Environment any only Push the content to that one server.
    • If communication with the selected server fails, dotCMS will randomly choose another server in the Environment and try the Push process again.
  • If Push to All Endpoints is selected, the content will be sent to all servers in the Environment every time a push is performed.

Important: Pushing to a Cluster

When pushing to a cluster, you must do one of the following:

  • Set the Push Mode to Push to One Server.
    • When you push to a single server in a cluster, the servers in the cluster automatically synchronize the content among themselves.
    • If you attempt to push to all servers in the cluster, different servers may end up with different copies of the same content, which will cause synchronization problems among the servers in the cluster.
  • Push to a Load Balancer placed in front of the cluster.
    • It is recommended practice to use a Load Balancer in front of a cluster, to help manage performance.
    • When you use a Load Balancer, it is recommended that you push to the Load Balancer, rather than to the individual servers in the cluster.

Endpoint Servers

An Endpoint server is configured within an Environment and defines an individual receiving server to Push content to. To create an Endpoint server click Add Server and enter values for the following fields in the popup:

ParameterApplies ToDescription
Server NameAll EndpointsA friendly name for the server.
TypeAll EndpointsThe Endpoint Type.
Address ToDynamic EndpointsThe DNS server name or IP address of the receiving server.
PortDynamic EndpointsThe port to connect to the server. This value defaults to 80, and should be set to whatever port is used to connect to the front-end of the server.
Authentication Token/File PathDynamic EndpointsThis can be either a token key or an absolute path to a file in the file system that contains a key.
The key must match the one configured in the Receiving server for its Authoring Server.
PropertiesStatic EndpointsThe Properties of the Static Endpoint.
EnabledAll EndpointsEnables or disables If checked it enables sending to this individual server.

Endpoint Type

Endpoint TypeDescription
Dynamic dotCMS HTTPA Dynamic Endpoint using HTTP (regular HTTP) protocol.
Dynamic dotCMS HTTPSA Dynamic Endpoint using HTTPS (Secure HTTP) protocol.
Static AWS S3A Static Endpoint writing to an Amazon Web Services (AWS) S3 Storage server.

Static AWS S3 Endpoint Properties

When you select Static AWS S3 for the Endpoint Type, you must set the value of several properties which specify how dotCMS connects to your AWS S3 server to upload your static content.


Note: Static Endpoints are only supported in dotCMS Enterprise editions for customers with a Site License (Platform level license). Please see the list of dotCMS versions for more information on features supported in different version of dotCMS.


The following table lists all of the properties recognized in the Static AWS S3 Endpoint configuration:

PropertyRequiredDefault ValueDescription
aws_access_keyYesMust be changedYour Amazon AWS Access Key ID.
aws_secret_access_keyYesMust be changedYour Amazon AWS Secret Key ID.
aws_bucket_nameYesdotcms-bucket-{hostname}-{languageIso}The pattern to use to generate the AWS S3 Bucket Name.
For more information, please see Bucket Name Variables, below.
aws_bucket_regionYesAutomated Region SelectionThe Amazon AWS Region your AWS S3 server is located in.
aws_bucket_folder_prefixNoNoneThe prefix property creates a subfolder(s) under the bucket - in this case for each language configured on each site.
aws_validation_bucketNoRandom Bucket NameThe bucket name used to validate the AWS S3 connection parameters and permissions.
For more information, please see the Push Publishing Permissions documentation.

The following default values are filled in when you create a new Static AWS S3 endpoint. Please note that, as described in the table above, you must change the values of the aws_access_key and aws_secret_access_key to appropriate values for your AWS S3 server configuration.

aws_access_key=myToken
aws_secret_access_key=mySecret
aws_bucket_name=dotcms-bucket-{hostname}-{languageIso}
aws_bucket_region=us-west-2

AWS S3 Region

The aws_bucket_region specifies the AWS region that the Endpoint will publish to.

  • If you do not supply a value for this property or if you select the region us-east-1:
    • dotCMS will connect to AWS S3 in a way that causes Amazon AWS to automatically select a region based on the geolocation of your dotCMS server.
    • Note that when you select the us-east-1 region the region is still automatically selected based on your geolocation due to a historic limitation in the way the AWS S3 API allows selection of regions (from a time when AWS S3 supported only a single region, which eventually became the us-east region).
      • If you wish to specifically choose an AWS region on the East Coast of the United States, you must specify us-east-2 instead of us-east-1.
  • If you select a region other than us-east-1 from the list of valid AWS regions:
    • dotCMS will connect only to the specific region you choose.

Bucket Name Variables

When specifying the aws_bucket_name property, you may add variables to the value of the property. These variables will be evaluated and replaced with appropriate values each time a push is performed to the Static Endpoint. The variables allow you to create multiple buckets for different sites and/or different versions of your sites as needed to both display all your site content in static form, and to maintain different static versions of your site(s) over time.

When you push to a Static Endpoint, if any variables are included which separate the content of the site (such as when the {languageIso} variable is included), the push will be performed to multiple buckets at the same time - one bucket for each appropriate value of the variables.

Special Note: Special Characters are NOT allowed in bucket names. The following non-alphanumeric characters will cause communication errors:

.. , ! : ; & ? $ * / \ [ ] = | # _ " " @ ( ) < >

For more information, please see the Amazon Bucket Restrictions documentation.

The following is a list of the static variables supported by the aws_bucket_name and aws_bucket_folder_prefix properties:

VariableDescription
{hostId}The identifier of your dotCMS Site.
This means that you will have a different bucket (or set of buckets) for each Site on your dotCMS instance.
{hostname}The name of your dotCMS Site.
This means that you will have a different bucket (or set of buckets) for each Site on your dotCMS instance.
{languageIso}The ISO language code for the language of the content.
This means that you will have a different bucket (and thus a different static site) for each Language you have configured on your dotCMS instance.
{languageId}The Language ID for the language of the content.
This means that you will have a different bucket (and thus a different static site) for each Language you have configured on your dotCMS instance.
{languageCountry}The country code for the language .
  • This means that you will have a different bucket (and thus a different static site) for each country (not just each Language) you have configured on your dotCMS instance.
  • This may be necessary or desired when language versions differ significantly between countries with the same language code (e.g. zh-CN vs. zh-TW).
{date}The date of the push (in the form yyyyMMdd-HHmmss).
This means that you will have an entirely separate static version of your site for each date you push to the Static Endpoint.
{date-FFFFFFFF}The date and/or time of the push in a format you specify by replacing the FFFFFFFF in the variable name with the date and time format.
  • For example, {date-yyyyMMdd-HHmmss} is equivalent to {date}.
    • For more information on how to specify the date and time format, please see the Java Simple Date Format documentation.
  • This means that you will have an entirely separate static version of your site for each date and/or time you push to the Static Endpoint.

Mixing Dynamic and Static Endpoints

You can mix Dynamic and Static Endpoints within the same publishing Environment. However it is important to understand that when mixing Dynamic and Static Endpoints in the same Environment, you should not select Push to One Server.

When you configure the Environment as Push to One Server and then push content, dotCMS randomly selects only one Endpoint in the Environment. If your Environment includes both Dynamic and Static Endpoints, dotCMS will select one of the Endpoints at random, which might be either a Dynamic Endpoint or a Static Endpoint, but not both. This will cause the Dynamic and Static sites to have different content and become out of sync with each other over time.

Instead, when you mix Dynamic and Static Endpoints in the same Environment, you should always select Push to All Servers.

Important Note: You should not select Push to All Servers when including a cluster in an Environment. Therefore if you mix the servers in a cluster (as a Dynamic Endpoint) with a Static Endpoint, you should include only one server from the cluster in the Environment.

Receive From Servers

The Receive From servers list specifies which servers are authorized to push content to your dotCMS server.

To add a Receive From server, click the +Add Server button in the Publishing Environments tab. A poup opens with the following fields:

ParameterDescription
Server NameA label to identify the sending server. The Server Name does not need to match the actual server name, IP address, or domain; however it's helpful to set the Server Name to the fully qualified host name (including the domain) to make it easy to identify the server.
Address FromThe DNS server name or IP address of the server that intends to Push content to the current instance server.
Authentication Token/File PathThis can be either a token key or an absolute path to a file in the file system that contains a key. The key needs to match the one configured in the Sender server.
EnabledEnables or disables the individual server within the environment.

Before first pushing content to an Environment containing Dynamic Endpoints, and periodically after the connection has been established, it is highly recommended that you run the Integrity Checker on the sending server to verify that there are no conflicts between the content on the sending server and receiving Environment.

Once the connection has been configured and validated, you can begin Push Publishing Content from the sending server to the receiving server(s).

Authentication Token/File Path

It is strongly recommended that you use the Authentication Token/File Path field to add an additional layer of security in the form of an authentication handshake between the sending and receiving servers. The use of an authentication key helps prevent a potential attacker from from sending content to the receiving server by “spoofing” (impersonating) the sending server.

If the value of this field is a path to a file on your dotCMS server containing text, dotCMS will read the contents of the file and use the string as the authentication key. Otherwise, dotCMS will use the string entered into this field as the authentication key.

The authentication key used must match on both the sending and receiving servers for any push publishing connection between the servers to work. If the authentication keys don't match, any attempts to push content (or perform an Integrity Check) will fail.