What to Know Before Push Publishing

Before setting up push publishing environments in dotCMS, it is very important to know best practices for the proper workflow, what can and can't be pushed, potential pitfalls, and how to troubleshoot problems. Knowledge of the following limitations and recommandations is vital to successfully manage push publishing.

Infrastructure

Single Authoring Environment

There should only be one Authoring environment.

In a push publishing environment, ALL changes to content should be made on the authoring server only, and then pushed to the Endpoint(s).
If two objects with the same name are created separately on two different dotCMS instances, attempts to push the object from one server to the other (with each server treating the other as an Endpoint) will create a conflict.
Conflicts of this type can be resolved using the Integrity Checker; however these issues should be avoided by only creating and editing content from a single Authoring environment.

Requirements

Matching Server Versions

Your sending server and any Dynamic Endpoints it pushes to should run similar stacks. In particular, it is very important that the versions (including both release and “flavor”, if appropriate) of all of the following match on all servers in your push publishing environment (both sending server and Dynamic Endpoints):

dotCMS
Java Virtual Machine (JVM)
Database
Application server

dotCMS License Version

To use the push publishing feature for Dynamic Endpoints, you must run an Enteprise Pro, Enterprise Prime, or Cloud dotCMS license.

To use the Push Publishing feature for Static Endpoints, you must run a dotCMS Enterprise version with a Site License (Platform level license).

In addition, you must ensure that each server in a push publishing environment has its own separate, unique dotCMS license. You cannot perform push publishing in any form unless each server's license is unique and valid.

For more information on features supported in different versions of dotCMS, please see the list of dotCMS features.

Recommendations

Use HTTPS

It is strongly recommended that all publishing environments featuring a production instance run in HTTPS.

Identify High Availability Needs

Whatever your intended use of dotCMS, it is important to identify where your architecture will most benefit from High Availability before you configure and build out your push publishing environment.

If you have many content editors editing high volumes of content, it is strongly recommended that you cluster your authoring server environment.
If your page traffic is high or front end performance of your site is important, you should consider using a cluster for your Production server environment.
- For very high traffic or performance needs, consider multiple clustered production environments in different regions and/or datacenters.

Capabilities and Limitations

When using and planning push publishing, it is important to understand the capabilities of the push publishing feature, and what types of objects and content can and can't be pushed.

What Can and Can't be Pushed

Content Pushed to Dynamic vs. Static Endpoints
What CAN be Pushed
Important Note: Push Publishing Dependencies
What can be Synchronized
What Can NOT be Pushed

Content Pushed to Dynamic vs. Static Endpoints

The types of content that can be pushed to both Dynamic Endpoints and Static Endpoints are the same; from the perspective of the sending server all the same types of content can be pushed regardless of the Endpoint. However the way in which different types of content is pushed varies greatly depending on whether the content is pushed to a Dynamic Endpoint or Static Endpoint.

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.

Specifically, when Dynamic Content is pushed to a Static Endpoint, that content is automatically converted to Static Content.

This means that, although all of the content listed in What CAN be Pushed, below can be sent to a Static Endpoint, once the content is received and served by the Static Endpoint it is no longer dynamic.

Finally, some of the types of objects which can be pushed are fully dynamic content that is not supported on a Static Endpoint. You may still push these types of content to a Static Endpoint, and the push will still succeed; however the Static Endpoint will not actually receive these types of objects in the push. These object types include:

Tags
Categories
Rules
Personas
Workflow Schemes
OSGI Plugins

For more information on Dynamic Content vs. Static Content and how each type of dynamic content is converted when pushed to a Static Endpoint, please see the Converting Static Content to Dynamic Content section of the Static and Dynamic Publishing documentation.

What CAN be Pushed

The following items can all be push published, either individually or in bundled groups.

Content Types
Content (including multi-lingual content)
Files
Folders
Pages
Templates
Containers
Widgets
Forms
Menu Links
Tags (from content with Tag fields)
Sites (Hosts)
Vanity URLs
Workflow Schemes (with Content Types)
- Note: Workflow Schemes can't be pushed directly; instead, to push a Workflow Scheme, push a Content Type the Workflow Scheme is assigned to. For more information, please see the Push Publishing Dependencies documentation.
Users (NOT recommended for Production Environments)
OSGI Plugins

Important Note: Push Publishing Dependencies

When any object is pushed, the needed dependencies to completely create and display that object are also pushed. For example, when you push a page, dotCMS will also automatically push Content on the page, Templates, Containers, and the folder(s) in which it resides, etc., as needed. For more information, please see the Push Publishing Dependencies documentation.

What can be Synchronized

In addition, the following can be push published, but when these types of objects are pushed, the objects on the sending server and Endpoint are synchronized. This means that all objects of the specified type are pushed to the Endpoint, and all objects which exist on the Endpoint that do not also exist on the sending server will be removed from the Endpoint. Categories can be both synchronized completely (from the categories manager), or pushed independently as dependencies of content.

What Can NOT be Pushed

The following dotCMS objects cannot be pushed and will need to be manually added to Dynamic Endpoints as needed:

Roles and Permissions
- It is very important for security, data integrity, and push publishing management that Roles be maintained separately on the sending and receing servers.
  - This ensures that users with editing and publishing permissions on the authoring envionment are not accidentally granted editing and publishing permissions on the production environment; all permissions on the production environment must be granted explicitly.
  - Therefore it is intentional that you can not push publish Roles; Roles must be explicitly created on each dotCMS server, to ensure that each environment has only the necessary Roles appropriate for that environment.
- Note: If you push user accounts, those accounts are pushed to the Dynamic Endpoint without any permissions assigned.
  - You must manually assign Roles and permissions to the user accounts after they have been pushed to the Endpoint.

Ways to Push Publish

Push Individual Objects

Individual objects can be pushed to an Endpoint one at a time in two ways:

Manually push publish a single object.
- Right-click an object and select Push Publish from the right-click menu.
Push Publish via Workflow.

Push Multiple Objects

In addition, multiple objects can be pushed to an Endpoint at the same time in all of the following ways:

Manually push multiple selected objects.
- (Select multiple items on a screen, then press the Push Publish button at the bottom of the screen).
Create and push Bundles of objects.
Download bundled content from the sending server and upload the bundle on a Dynamic Endpoint.

Note: A bundle which is created and downloaded from one dotCMS instance may only be uploaded to a different dotCMS instance. You can not download a bundle from a server and later upload it back to the same server.

Push Publishing Migrated Legacy Relationships

One sided Relationship fields on Content Types were added in the dotCMS 5.1 version. Before push publishing on a server/endpoint that was recently upgraded from a pre-5.1 to a post-5.1+ dotCMS version, make sure to follow both the migrating legacy relationships and the Push Publishing Migrated Relationships documentation carefully.

How Push Publishing Permissions Work

Permissions work differently when pushing to Dynamic Endpoints vs. Static Endpoints.

When pushing to a Dynamic Endpoint, the overwhelming majority of push publishing issues can be prevented by setting proper user and Role permissions on your authoring server and your Endpoint. When pushing to a Static Endpoint, Push Publishing rights depend both upon the Permissions on your authoring server and appropriate rights in your AWS S3 server.

Before performing your first push, make sure to read the Recommendations section of the Push Publishing Permissions documentation, and ensure that you understand how both User Permissions and Content Locks work when pushing to a Dynamic Endpoint.

How Taxonomies are Pushed

Tags and Relationships

When pushing to a Dynamic Endpoint, new Tags, and Related Content push publish along with each piece of content that uses them.

The tags/relationships on each piece of content will be compared to existing tags/relationships on the receiving server:

If the tags/relationships already exist on the receiving server, they will be associated with the content.
If the tags/relationships do not exist on the receiving server, they will be created on the receiving server and then associated with the content.