Setting up remote publication

Overview

What is remote publication?

The remote publication is the possibility to have an environment dedicated to the edition of content (authoring) and a totally separate environment dedicated to the delivery (called distant publication server/environment) of the pages for the site visitors. Each environment is autonomous (they have their own database) and are usually in a different DMZ. The communication between servers uses HTTP/HTTPS protocols (it is strongly advised to use HTTPS).

This type of architecture meets specific requirements - in particular regarding security - but it results in a number of changes in the way the platform works and it requires certain rules to be observed.
The remote publication is performed per site: it is possible to manage several sites on the authoring environment, and only have a few of them being remotely published on the distant publication environment. Sites can be remotely published to different publication environments.

How does it work?

The remote publication is the system that copies all the already published contents of a site from the authoring environment to the distant publication environment. The content creation and publication on the authoring server remain the same as in a regular Jahia environment, the remote publication is an extra process that pushes the live contents to the remote server. It is a 3 step process:

1. Contributors create content in the authoring environment. The content is only available in preview in the authoring environment

2. Reviewers publish the content on the authoring environment: at this time the content is not yet available on the distant publication environment, but can be browsed in live mode in the authoring environment. One more action is required to make the content available in the distant publication environment: the execution of the remote publication.

3. The remote publication can be executed with any of the following ways, from the authoring environment (push):

• Manually from the site settings of the site to be remote published
• Automatically using scheduled executions (configured when setting up the remote publication)
• As a final step of a publication workflow

Several verifications are done in the step 3 which can prevent the remote publication to be executed (for instance if the distant publication server does not have the same module versions as the authoring one). After the execution of the remote publication, a comparison is performed in order to ensure that there are no inconsistencies between the source and remote sites.

Typical use cases

A remote publication environment answers the requirement of having the contribution part, and some sites behind a firewall, while having the public sites in a DMZ.

Setting up a remote publication environment

Installation

There are several key points to keep in mind when setting up a remote publication environment:

1. The authoring and distant publication environment need to be on the exact same version of Jahia.
2. An authoring server can have remote publications set to several distant publication servers.
   

   

3. But one distant publication server can only be related to one authoring server. This is done to avoid conflicts.
   

   

4. Chained remote publications are not supported:
   

   

5. It is necessary to deploy the Jahia Remote Publishing module on the authoring environment. You can find the module on the store.
6. The servers of the distant publication environment needs to be installed using the distantPublicationServer operating mode. In jahia.properties, set

operatingMode = distantPublicationServer

Logs

By default Jahia stores in a log folder (named jahia-remotepublish) on the distant publication server all the journal entries received when a remote publication is executed. For security reasons, the values of the content properties do not appear in the logs. This folder is located in the default log folder of your environment (in the same location as the jahia.log file). One file is created per remote publication execution, and contains the journal entries in a json format.
Please consider archiving/cleaning these log files as they can use a lot of disk space depending on the size and number of remote publication. You can also disable this logging feature by setting the jahia.remotepublish.logReplayData configuration property to false in the jahia.properties file of the distant publication environment:

jahia.remotepublish.logReplayData = false

IP white listing for allowing the execution of Remote Publications to selected IPs only

To limit the authorized instances which are allowed to start a remote publication on a distant publication environment, the list of allowed IPs can be configured on the remote instances.

For this purpose, list the relevant IPs in the file <DX-install-directory>/digital-factory-data/karaf/etc/org.jahia.modules.remotepublish.cfg.

Jahia will consider this list of IPs and only allow requests coming from these instances to start a remote publication.

External Data Providers

If the remote published site(s) use any external data provider, you have to mount them as well on the distant publication server.

Note that for the moment, the remote publication only supports global mount point: you cannot use an external data provider mounted in a site folder.

Users and groups

Global users and groups are not part of a remote publication. Therefore if you have set live roles for such users and groups, you need to be sure to have them as well on the distant publication server. If these users and groups come from one or several user and group providers (e.g. an LDAP provider) on the authoring environment, you need to mount them as well on the distant publication environment.
Users and groups created from the site settings are included in the remote publication, and do not require to be recreated on the distant publication environment.
If you only set edit roles, then you do not have to mount the user and group provider to the distant publication environment. However, these users with edit roles will appear as “inconsistencies” when performing a comparison of the site.

Roles

Roles created and modified in the administration are not part of the remote publication. As Jahia does not have a feature to export / import roles from the administration interface, we recommend to define your roles in modules or template sets. The roles will be imported and available in the administration when the module is deployed on the server.
For instance (we do that with the jahia default module), see the roles.xml:

https://github.com/Jahia/default/tree/master/src/main/import
The export and then re-import of a role can be done by exporting it to an xml file from the jcrBrowser ( http:[host]:[port]/[context]/tools/jcrBrowser.jsp ). Then use the exported xml in a dedicated module that you deploy on the distant publication environment.
To export and then re-import all the roles, you can use the web project import feature. On the authoring server, in the Web projects administration page, export the staging content of the site (or create an empty site for this operation, or a small site or the system site). Import the zip of this site on the distant publication server, but in the first step of the import, select only the box “roles.zip” and uncheck the other boxes, then click on “Next”. The roles from the authoring server are now available on the distant publication server.

Portlets

The remote publication supports portlets. You need to deploy the portlet on both authoring and distant publication environments to make it work.

jExperience

jExperience is fully compatible with a remote publishing architecture. Though a precise method must be applied. Please find the detailed setup procedure here.

Forms

1. On both Authoring server and Distant Server, Forms module should be deployed/started on authoring and distant publication server.. The module version has to be same on both the servers.
2. Create a site with same key on both servers. Enable same version of Forms Core module on both sites on both servers.
3. Authoring server only: Forms are created, managed and published only in authoring environment. Once published, forms can be viewed in Live mode on the authoring server.
   Note: Do not submit forms from the authoring server.
4. Authoring server only: Enable Jahia Remote Publishing module on the site which you want to publish.
5. Authoring server only: Execute remote publication on the authoring server. Once the remote publication is finished successfully, forms are also accessible in ONLY LIVE MODE on distant publication server
6. Distant Publication Server:
   • Those forms which are accessible in LIVE mode of Authoring server, can be viewed/ submitted in LIVE mode of DIstant Publication Server
   • As the forms are only submitted on distant server, Form Submission Results can be found in View/Exploit Form Results on the distant server itself, accessible from the site settings of the remote site
   • User should also have rights to view the Forms results depending on their role specified under Site Roles as shown in the screenshot below:
     

     

(Forms Results Analyst would be the most suitable role in this case)

Translation.com connector

This module needs to be installed on the authoring environment only, as it is used to translate content in the default repository. Once the content is translated, it has to be published and so it will be part as the following execution of the remote publication, like other contents.

Permissions

The remote publication feature comes with three permissions, available for the edit and site roles :

1. “Publication choose remote”  (which can be found in “Permissions on current node/Workflow tasks”): this permissions allows the user to complete the last step of the “Simple Publication with remote publication” and “Complex Publication with remote publication” publication workflows, which consists in executing a selected remote publication. By default, this permission is set for the “Reviewer”, “Editor in chief roles” and “Site administrator”.

2. “Remote publication manager” (which can be found in “Permissions on current site/user interface/Managers”): this permission gives access to the “Remote publication” panel in the site settings. From there, a user with this permission only, can execute a remote publication and see the execution history. This user cannot access the administration tools: creation/edition of a remote publication configuration, execution of a site comparison or forcing a remote publication. By default this permission is set for the roles “Editor”, “Editor in chief”, “Reviewer” and “Site administrator”.

3. “Remote publication admin actions” (which can be found in “Permissions on current node/permission on modules”): this permission grants access to the administration features of the  “Remote publication” panel in the site settings. By default this permission is set for the role “Site administrator”.

Creating a remote publication

Please read the “Technical overview” and “Set up a remote publication environment” before.
Here are the steps to create a remote publication. We assume here that you already have a site (called source) published on the authoring server.
1. On the distant publication environment, ensure that all the modules used by the site (including the template set) are started, and that they are in the same version as on the authoring environment

2. Create a new, empty, site on the distant publication environment, using the same templates set as the source site. You do not have to select any module.

3. On the authoring environment, enable the “Jahia Remote Publishing” module on the source site

4. In the source site, navigate to Administration>Sites>Remote publications.

5. Click on New Remote publication. The New Remote publication page opens.

6. Fill the form:

• Name: Choose an explicit name for the remote publication
• Source node: this is the site node, shown for information
• Target server URL: enter the URL of the distant publication server. If you have a cluster as a distant publication environment, you must type the URL of the processing node. Please include the context of the webapp of distant publication server. HTTPS protocol should be used to avoid sensitive data to be sent unencrypted across the network. For instance: https://127.0.0.1:8443/remote
• Key of the target site: Type the sitekey of the site you created at step 2
• Password of the distant site user: Type the password of the root user of the distant publication environment
• Schedule automatic execution: Click on the “Add” button if you want to use CRON jobs to execute the remote publication. An interface is then displayed to create your CRON expression.

    

 This step is not mandatory, as remote publications can be also executed using a workflow or manually from the “Remote publications” panel of the site settings.

• Test settings: By leaving this option checked, Jahia will perform a verification, when clicking on the “Add” button, that all the settings are correct and that a remote publication can be executed on the distant publication environment. The verifications performed are:
  •     The target URL is accessible
  •     The target site exists in the distant publication environment
  •     The root password is correct
  •     The module versions match
  •     The IP of the authoring server is allowed by the distant publication server
  •     The distant server URL of the remote publication is different from the source one
  •     The remote publication of the site is not blocked on the distant publication server
• Ignore publication history: In case this option is checked, when the "Add" button is clicked, the Jahia will schedule a background job to "recreate" the site in the journal specifically for this remote publication. "Recreation" of the site in the journal means that a minimal number of new journal entries, necessary for remote publication of the site on the distant publication server from scratch, will be created, while any previously existing journal entries will be ignored by the distant publication server on remote publication execution. This can be useful when creating a new remote publication of a site that has a long history of changes, in order to minimize the time to publish it from scratch on the distant publication server.
• Click on the “Add” button

The remote publication is now created, but has not been executed yet.

7. In the confirmation window, click Execute remote publication.

8. Click on “Execute remote publication”. Note that the remote publication is executed in the background.
9. Once the remote publication is finished, the column “Last execution” is updated

10. You can edit the remote publication configuration at any time by clicking on the “Edit” button (

)
11. You can create other remote publications for this site at any time, using different distant publication environment.

Executing a remote publication

This part describes the 3 ways of executing a remote publication. Keep in mind that every time a remote publication is executed, everything that was published on the site in the authoring environment is remotely published: you cannot select which already published parts of a site can be remotely published. After every execution of the remote publication, the remote site is similar to the source site.

Planned execution using CRON jobs

The planned execution of a remote publication is set in the remote publication configuration. This type of execution is automatically done at the specified time and does not require any manual intervention. CRON executions will make some delay between the publication on the authoring environment and the public availability, but can be chosen for better performances as the HTML cache will not be invalidated during 2 synchronizations on the distant publication environment.
It is possible to see the scheduling and when the next automatic execution will happen from the “Remote publication” panel in the site settings:

Manual execution

Manual executions can be used along with CRON executions when the update has to be pushed without waiting for the next planned execution of the remote publication.
In the Remote publication panel of the site settings, you will see all the remote publications created for your site. You can manually execute a remote publication by clicking on the Execute remote publication button . In the confirmation window click Execute remote publication.

Workflow execution

The remote publication can be executed as a step of a workflow (usually the last step of a publication workflow which includes the execution of a remote publication, but this is not a requirement). By using the workflow execution you will not face the delay encountered by CRON executions, but it will generate the same cache invalidations as if the remote publication based architecture was not used.

The Jahia Remote Publishing module comes with two workflows (a one step publication workflow with remote publication, and a 2 step one with remote publication). After the publication on the authoring environment, there’s an additional step where the user can chose the remote publication to execute:

Workflow dashboard showing the different steps of a workflow

In the final step of this workflow, the user needs to select the remote publication to execute

Once the workflow is selected, the user needs to click on the Launch the selected remote publication button in order to execute the remote publication. The user can also chose to not execute the remote publication by clicking on the Skip remote publication button. In this case the content that was just published on the authoring environment is not yet available on the distant publication server. It will be after the next execution of the remote publication.

Reminder: the execution of a remote publication as part of a workflow will not only remotely publish the contents involved in the publication workflow, but also all the contents that were previously published on the site in the authoring environment and not yet remotely published.

Remote publication setting panel

The remote publication setting panel is accessible from the site settings.

Execution history

The results of every RP execution are stored and can be seen on the history page, which can be accessed by clicking on the “Advanced” button () corresponding to a remote publication from the remote publication setting panel:

For each execution, there is an entry in the table with its status and the number of operations. In case of failure, there is a message explaining the error and a “details” button to get more information.

If an execution failed because of a module inconsistency, the details button will show the list of the modules (and their versions) which are missing on the distant publication environment:

If the execution of a remote publication or a comparison raised inconsistencies, you can access its list of the inconsistent nodes from the history table, by clicking on the “Details” button () shown in the “Details” column. The comparison report will then show all the contents that are not the same on the distant publication environment:

3 types of inconsistencies can be shown in the comparison report:

• Inconsistent node: the node properties or child node are not the same between source and remote
• Node not found: the node is not found on the remote server
• Wrong path: the node is found on the remote site but not at the same place as on the source site

Forcing the remote publication of a content

It is possible to remote publish content, even if it has already been published. This helps to fix content inconsistencies between the source and the remote servers.

This is done by adding a new journal entry for the current configuration and will be replayed at the next remote publication execution. You will be able to see it as a remote publication execution in the remote publication history.
You can select the contents for which the remote publication will be forced during the next execution from 2 different screens:

Advanced tools

You can access the advanced tools by clicking on the “Advanced” button () corresponding to a remote publication from the remote publication setting panel:

From here you can set a Force remote publication:

• Node path: the path of the content to be published. The path must match the current site or the system site path.
• Save and restore user generated content: check this option if the content you published has UGC on it. This way, UGC will be saved before republishing the content, and then restored at the end.
• Include sub-pages: if the content you publish is a page, or has subpages, checking this option will also force the publication of all the sub pages. If unchecked, only the node path page will be force published.

In the confirmation window, click Force publication on next execution.

Comparison report

From the comparison report (see “Execution history”), users with the “remote publication admin actions” permission can select the nodes to be forcedly re-published during the next execution of the remote publication. For these, they need to check the box corresponding to the nodes, then click on the “Force remote publication” button.

In the confirmation window, click OK.

The contents on which a re-publication is forced should be chosen carefully: either choose all nodes or the parent node if it can be identified.

For example:

The comparison shows a list of nodes like this:

• /sites/mySite/home/news
• /sites/mySite/home/news/news-area/news1
• /sites/mySite/home/news/news-area/news2
• /sites/mySite/home/news/news-area/news3

If you select any news content, but not the /sites/mySite/home/news, then the remote publication will fail. So this node must be selected (either only this one - which would be enough, or all nodes). We recommend to identify the parent node and republish that one as a first step.

The force remote publication of the inconsistencies will be executed on the next remote publication execution.

Performing a comparison between authoring and remote site

It is possible  to compare the source and the remote sites in order to identify potential differences. This comparison is manually triggered from the advance tools on a remote publication comparison (it’s possible to compare the complete site or a sub tree by specifying the path of the origin node):

In the confirmation, click OK. If a comparison job is already scheduled or running then a second confirmation displays. Click OK in the second confirmation dialog.

Then the comparison will be executed in a background job, and the result will be visible in the history:

...

The comparison is also automatically executed at the end of each remote publication, to compare the published nodes. The results are also visible in the history:

For each comparison results from the history it’s possible to click on:  To see the details of the inconsistencies:

For each inconsistencies displayed here it’s possible to force the remote publication of the associated node ( see Forcing the remote publication of a content )

Administration tools

Block incoming Remote Publications

It is possible to block all incoming remote publications for a site on the distant publication environment (useful during a contribution freeze or during maintenance time). To do this, you need to open the Repository Explorer, then open Content Editor of  your site node using the "Edit" entry in the contextual menu:

You will then see a tab “Remote publication”. You can check the box “Block incoming remote publications”. We recommend to add a comment which describes why the remote publication execution is currently blocked:

This message will be shown in the error log (in case of scheduled executions) as well as in the UI on the authoring environment (in case of a manual execution of the remote publication):

By unchecking the box, you will allow again incoming remote publications.

System tools

You can access a dedicated system tool page for remote publication that shows all the journals on the server. You can reset the journal for a site, see the journal entries, purge old entries of a journal and change the value of the lastReplay property.

You can access the system tool page using the following URL:

http:[host]:[port]/[context]/modules/remotepublish/tools/remotePublishManagement.jsp

To access the system tool page, you require a tool user session. You must be logged in as root or a user who is a member of the System administratot system role. For information on Jahia Tools permissions, see Managing roles and permissions.

Reset the journal

Reset the journal will remove the current journal, and recreate it from the current content. Note that once reset, the remote sites associated to the journal will have to be recreated, as the journal will contain entries corresponding to the site creation. The next version of Jahia will allow the creation of new remote publications even after a purge of the journal.

Clicking on "view details" let you see all the entries for a journal.

View and purge journal entries

From the detail view of a journal, you can see the last entry processed by any remote publication: the name of the remote publication is displayed next to the entry ID. You can also see all the journal instructions within an entry by clicking on "view details".

You can also purge a range of entries by clicking on "Purge this and all previous entries". This will remove this entry and all the previous ones for this journal. Once entries have been purged, it will be necessary to reset the journal before creating a new remote publication (which means to also recreate all the existing remote publication). The next version of Jahia will allow the creation of new remote publications even after a purge of the journal.

The journal can also be purged by using the action "purgeJorunal" on the corresponding site, using an eventDate parameter. All the entries prior or equal to this date will be purged. This action needs to be called using a root session:

http://localhost:8080/jahia/cms/render/default/en/sites/digitall.purgeJournal.do?eventDate=1495453418467

Change the value of the lastReplay property

From the previous screen, where all the journal entries are displayed, you can also change the value of the lastReplay of a remote site. This is very useful when fixing issues, as you can choose when to start again a remote publication.

For this you need to select the remote publication corresponding to this remote site, and then type the wanted ID of the journal entry. Please note that the entry selected will NOT be replayed, Jahia considers it as already being replayed. Therefore, if you want to replay starting from a specific entry, you need to select the previous entry ID. Or select the last one (in our example the 23) in order to make the remote publication “to date”.

There’s a special handling for the systemsite journal: when updating systemsite last replay for a remote publication configuration,

we also update all the other configurations that share the same remote server URL.

Troubleshooting

Suggested actions

When an issue occurs during the execution of a remote publication, it is necessary to look at the logs, they will guide you to find what went wrong. The history report of the remote publication can also give you information.
Depending on the issue, the resolution can simply be to fix something on the distant publication server (for instance removing a node in from the tools) or in more complicated cases, the solution can be:
1. From the remote publications tools available at the following URL http:[host]:[port]/[context]/modules/remotepublish/tools/remotePublishManagement.jsp , you need to change the last replay for the failed remote publication and set it to the last entry
2. From the remote publication panel in the site settings, perform a full site comparison
3. Force the remote publication of the identified contents: avoid forcing the remote publication of the whole site and try to select only the faulty contents or their parent nodes
4. Execute the remote publication again

Handle network connectivity issues

Splitting remote publication in multiple chunks

The parameter jahia.remotePublicationService.replayLogRecommendedSizeLimit in jahia.properties allows to set a threshold for the size of the request between authoring and public server. The system will try to split into multiple chunks the remote publication if the size is exceeded. This allows to have smaller and faster requests between the 2 servers, instead of one potentially big and long request. Please note that the final size of the data sent will always be higher than the set limit. It will stop writing when the data are bigger than the threshold, but not before. Since the data are gzipped, the size may grow by big steps. Also note that a binary file uploaded in the jcr will never be split during its remote publication - it will always be published in one single chunk.

What happens if a connection break during remote publish execution ?

If a connection breaks while executing the remote publication, it will still continue to run on the public server, but the authoring server won't get the answer. It will stop and show an error. Also, if the remote publication was split in multiple chunks, it won't sent next chunks immediately. Re-executing the remote publication will always check the current status of the public server before sending any data - remote publication will restart where it was stopped, and the status will be reset to "successful" when everthing is back in sync.

Migration of a remote publication environment

Please follow the “How to upgrade” procedure corresponding to your environment version when migrating all the nodes of your remote publication environment. All the authoring and distant publication server nodes must be upgraded at the same time. It is not possible to have the authoring environment in a version x and the distant publication environment in a version y.
After migration of the nodes, all your remote publication configurations are ready to use. No additional action is required in order to execute remote publications.

Technical overview

This part explains how the remote publication work, what is required to make it work properly and what are the limitations

Journal

Principle

In order to replicate the live part of a site on the distant publication server, the authoring server writes in a journal all the operations performed in the live repository for the site (node creation, update, deletion, move). When the remote publication is triggered, the distant publication server checks the server integrity (modules and definitions) in order to receive this journal and replays all these operations in the same order as they happened on the source server, base on the last time the remote publication was executed (property lastReplay of the site on the remote publication environment). This journal system makes it possible to have UGC on the remote site, allows the usage of rules on the target server and is faster than copying the entire nodes after every remote publication. This systems makes it possible to remotely publish a site to several different targets, which may not be updated at the same time.
But this system also has its constraints. It is not possible to remotely publish only one part of the site, all the published contents will be part of the remote publication, this can been seen as a synchronization operation between the live workspace of both servers for a given site. For instance if both the pages A and B are published on the authoring server, you cannot only remotely publish the page B, both pages will be remotely published during the remote publication execution. The reason is that, contents might be referencing other contents, or might be created under a content which was not already remotely published. When using a workflow to execute a remote publication, you need to keep in mind that the whole remote publication will be executed, and not only the contents which were involved in the workflow. The contents of a site will be remotely published in the same order as they were originally published. The remote publication system is not another fine level of publication, it’s the possibility to “copy” the live part of a site on a different server.
The journal lists the modifications performed in the live repository of a site, but does not include the content definitions used, as content definitions are managed at the server administration level. Therefore, it is primordial to ensure backward compatibility of content definitions. For instance if a content was created with a definition in its V1, the corresponding operation is written in the journal but it might be remote published later, when the definition is now in V2 (after the deployment of a new version of the module) in the distant publication server. In order to avoid potential issues, definitions have to be backward compatible, so they can be interpreted successfully. Please see https://academy.jahia.com/documentation/digital-experience-manager/7.3/development/jahia-dx-definitions-modifications for more details about definition modifications.
In the same idea, if a content of a type provided by a module A is created, published and then deleted, all these operations will be written in the journal. Then module A is undeployed from the the authoring server. The creation and deletion of the content still appear in the journal, which will lead to issues when the journal will be replayed on the distant publication server, if module A is not deployed on it. Such case is detected and the remote publication will not be executed. One will have to deploy the module A on the distant publication server in order to be able to execute the remote publication. After the execution of the remote publication, module A can be undeployed from the remote publication server. Keep in mind to follow the same module deployment process on both authoring and distant publication environments.

Before replaying the journal, an integrity check is done to :

• Checks that the nodetypes involved in the journal to be replayed are available
• Checks that the modules enabled on the site are the same on both remote and authoring

As mentioned, there is one journal per site on the authoring environment. The same journal is used for all the different remote publications of the site.

Here’s the remote publication sequence:

1. Content is created in the default repository of the authoring server
2. Content is published in the live repository of the authoring server
3. The operations performed during the publication are written in the journal of the site
4. The remote publication is triggered (by workflow, manually or by CRON job), a background job to execute the remote publication is created and scheduled for an immediate execution.
5. The authoring server requests and receives the lastReplay property  (the last time the remote publication was successfully executed on the remote site) of the site from the remote publication server
6. The authoring server then sends for verification to the distant publication server:

• the list of modules activated on the site (and their started version, see the Module chapter)
• the nodetypes required by the entries of the journal to be replayed

7. The distant publication server verifies this list of modules and nodetypes. It also verifies that the remote publication is not currently blocked and that the IP of the authoring server is allowed
8. After verification, the distant remote publication server notifies the authoring server that the verification was successful
9. Knowing the lastReplay value, the authoring server sends the journal entries created after that date, and a hash of the modified nodes that will be used for verification
10. After reception of the journal entries, the distant publication server replays them in its live repository
11. At the end of the replay, the distant publication server generates a hash of the nodes that were processed during the remote publication execution, and compare them with the hashes sent by the authoring server. The result of the comparison is sent back to the authoring server, and will be displayed in the history interface of the remote publication.

Journal creation

In order to set and use the remote publication on a site, the module has to be enabled on it. The journal is initialized when the Jahia Remote Publishing module is enabled on a site. At this point, the journal contains the instructions to recreate all the nodes currently present in the live repository under the site node to be remotely published. The distant site will be created/initialized by replaying this first set of instructions.

The journal is removed when the Jahia Remote Publishing module is disabled for the site. Which means that if you disable the Jahia Remote Publishing module on a site, and then re-enable it, the journal will be re-initialized and therefore cannot be used on an existing remote site. You will have to create a new remote site, and execute the remote publication again.

Stopping the Jahia Remote Publishing module will not delete the journal, however all the operations happening in the live repository while the module is stopped will not be written in the journal. And so they will not be part of any remote publication, which will most likely leads to issues or inconsistencies. Such inconsistencies can be fixed by using the force remote publication feature.

Points of attention when resetting the journal of a site

Several points should be kept in mind when enabling the Jahia Remote Publishing module on a site or when resetting the journal of a site:

• Avoid importing a site when a journal is (re)created
• Avoid creating contents which are “autopublished” on the site when its journal is being (re)created
• If the remotepublish module is enabled or disabled on a site by mistake, then wait for the background jobs related to such operations to finish before disabling or enabling again the module on the site

Modules

1. The modules used by the sites remotely published must be in the same version and in the same states on both authoring and distant publication environments. A verification is done before every execution of the remote publication that the modules match: the remote publication is not executed if the verification is not successful. However, this verification is done only for the template set module and its dependencies, and the modules enabled on the site. It is not done for the dependencies of the modules enabled on the site.
2. Therefore, the module lifecycle has to be the same on both authoring and distant publication servers: when deploying a module or a new version of a module on the authoring environment, the same operation needs to be done on the distant one, to ensure consistency between them. This also applies when stopping or undeploying a module.
3. Content definitions must be backward compatible, as a content created on the authoring server in V1 must be able to be replayed on the remote server using the V2 of the module. Please see https://academy.jahia.com/documentation/digital-experience-manager/7.3/development/jahia-dx-definitions-modifications for more details about definition modifications.
4. A module check is done before executing every remote publication:

• Modules that are started and enabled on the source site (template set of the site, dependencies of that templates set and modules directly enabled on the site) should be in the same state and version on the distant publication environment (but they do not have to be enabled on the remote site, c.f. “4. Create a remote publication”). If it is not the case, an error message is displayed to the user, an e-mail is sent to the server administrator and the remote publication is rejected.

5. Before executing every remote publication, Jahia verifies that the nodetypes of the contents being remotely published are registered in the distant publication server. If it is not the case, an error message is displayed to the user, an e-mail is sent to the server administrator and the remote publication is rejected.

Rules and interceptors

Rules and interceptors need to be used with caution in a remote publication environment. As the remote publication replays on the distant publication server the operations performed in the live repository of the authoring server, you need to ensure that rules and interceptors are not executed on both authoring and distant environment, otherwise the operations will be executed twice (the first time when replaying the modification, and the second time when executing the rule or the interceptor).
Keep in mind that:

• The distant publication server will only write in the live workspace during a remote publication execution, therefore only the rules coming from live-rules.drl files will be executed at that time.
• Default rules can be executed when writing in the default workspace by implementing a custom mechanism.
• Rules that create contents or modify nodes on the distant publication server need to be used very carefully, as the site on the distant publication server is a “copy” (it also contains UGC) of the live version of the site on the authoring environment. These kind of rules will make differences on the source and remote site that may be troublesome.

Rules and interceptor should not write in the live repository, but only in the default one in order to avoid issues in a remote publication environment.

Auto-created nodes

The remote publication supports auto-created nodes when they are added in the default repository and then published.

The remote publication does not support for the moment mixins with auto created subtypes added in live, as these mixins add nodes in the live repository without writing the operation in the journal. Keep in mind that Jahia strongly advise not to add mixins on nodes in the live repository only on the authoring server of a remote publication environment. This type of implementation is usually used to handle user generated contents.

User generated content

The remote publication supports User Generated Contents (UGC). These UGC need to be created on the distant publication server, and not on the authoring server. As a consequence, if the distant site is deleted, all the UGC created in this distant site will be deleted.

These UGC need to be stored as subnodes and not properties of existing nodes.

To ensure that UGC are created only on the distant publication server, you can use the following code in the view of your content to ensure that the UGC will be created on a distant publication server :

<c:if test="${renderContext.ugcEnabled}">

//code of your submit button, or to enable the submit button

</c:if>

Note that the code present in the “if” condition is only executed in live in a non remote publication environment, and only in live of the server installed as distantPublicationServer if the remotepublish module is enabled on the site. In other words, the code will not be executed in the following cases:

•  In live when there is no remote publication
• In live of server not displayed in the following cases:
•  In the studio
• In edit mode
• In contribute mode
• In preview
• In live on the authoring environment of a remote publication  

It’s important to keep in mind that since UGC are stored as nodes, they will be lost if the parent node is deleted on the authoring server, and then this deletion is remotely published.

To keep in mind if the rules above are not enforced:

Jahia does not support UGC being created on the authoring server. However, with the current mechanism these UGC created on the authoring server will still be written in the journal, and then part of the remote publication, which can lead to inconsistencies, to the overwrite of UGC on the distant publication server or to the failure of the remote publication execution.
In the case of UGC being stored as properties (e.g. the Jahia rating and Jahia Poll modules), these UGC will be deleted if the content is being republished. They will also be overwritten after the execution of a remote publication if UGC are set on the live repository of the authoring server. The following modules are safe to use with the remote publication:

• Jahia Blog
• Jahia Contact
• Jahia Forum
• Jahia Bookmarks
• Jahia Spam Filtering
• Jahia Social module
• Jahia Social Sharing
• Jahia Twitter
• Jahia Wiki

Shared content between sites

Shared content can be stored either in the system site (like categories, which are stored by default in in system site), or in any other site.

System site

As soon as a journal is created for a site, a journal is also automatically created for the system site. Each remote publication processes first the system site journal. The system site contains shared content such as categories.

Other sites

If a remote publish site has references to content from another site, both sites have to be individually remotely published. The site that contains the referenced content must have the same site key on both environments, local and remote. The references are resolved once the site that contains the referenced content is remotely published.