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.
- Capabilities and Limitations
- Additional Recommendations
- Correcting or Reversing an Unwanted Push
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.
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):
- Java Virtual Machine (JVM)
- 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.
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.
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:
- 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)
- Menu Links
- Tags (from content with Tag fields)
- Sites (Hosts)
- 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.
What Can NOT be Pushed
The following dotCMS objects cannot be pushed and will need to be manually added to Dynamic Endpoints as needed:
- Vanity URLs
- Roles and Permissions
- Note: If you push user accounts, those accounts are pushed to the Dynamic Endpoint without any permissions assigned, and 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.
How Push Publishing Permissions Work
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
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.
Category taxonomies in dotCMS cannot be push published individually. When you push publish from the Categories view (to an Environment that contains a Dynamic Endpoint), ALL of the categories from the sending server are synchronized with ALL of the categories on the Endpoint.
Before pushing Content Types that have Category fields which utilize a new category, you must synchronize categories from the sending to the Endpoint, to ensure that all categories exist and are up-to-date on the receiving server.
Synchronize Categories Before a Push
When pushing to an Environment containing a Dynamic Endpoint, push to synchronize Categories after any new category or subcategories are created, or before any large push.
Categories can not be pushed individually, and a new category will not automatically be pushed when a piece of content that uses that category is pushed. For more information, please see Categories, above.
Don't Modify Workflow on the Production Server
You should never create or modify workflow tasks on a Dynamic Endpoint when that Endpoint is configured to receive pushed content from another server. The workflow on the Endpoint will be overwritten by the workflow from the authoring server when content is pushed.
Correcting or Reversing an Unwanted Push
If you make a mistake or wish to reverse a push of content, you can make corrections using one of the following methods (for both Dynamic Endpoints and Static Endpoints):
- Edit the object(s) and push again.
- Note: You can revert content to a previous version from the Content History tab.
- Perform a Push to Delete to remove the object from the Endpoint.
- You should NOT manually unpublish or revert the changes directly on the Endpoint.
- Doing this can cause conflicts that will prevent push publishing from working correctly in the future.
- You can only perform a Push to Delete if the object you wish to remove from the Endpoint still exists on the sending server.
- If you have deleted an object, there is no object to push, so you can not perform a Push to Delete.
- Using a Push to Delete removes the selected object(s) from the Endpoint.
- If you wish to revert to the version of the content that existed before the original push, you must edit the object(s) and push again, instead of using Push to Delete.