Backing up and restoring Jahia

October 8, 2024

Backing up Jahia

There are two ways of backing up Jahia. You can:

  • backup at the data level to be able to restore your environment after performing a fresh install of the application
  • backup at the system level to ensure that you have complete backup of the system including the application

Backing up at the data level

When you backup at the data level you perform a database dump, backup runtime data and configuration files, so that you can restore your data and reinstall Jahia when needed.

To ensure that the backup does not have any inconsistencies because of heavy write operations or module deployement, the following options are recommended before performing any back up operation:

  •  Shutdown the Jahia server and backup.
  •  Activate Full read-only mode and backup. With Full Read-only mode, your module must have been developed to take care of this mode so that the users who try to write into the JCR will not receive errors

Performing a database dump

A database dump contains a record of the table structure and the data from a database, usually as a list of SQL statements. A database dump is useful way to back up a database so that its contents can be restored in the event of data loss or if you want to reuse an environment. 

There are many proprietary and open source software products that can perform a database dump for many types of databases. Here, the example shows MySQL.

mysqldump -urootUser -p Jahia > jahia.sql

Jahia runtime data

If you have chosen to store the binaries in your database, just skip this step

In the configuration wizard, if you chose filesystem-based binary storage (default option) you need to backup the JCR reposiroty.

The defaut location is digital-factory-data/repository.

If you changed the location of the datastore folder, you have to backup that folder. On a cluster environment any node can be use to perform the backup. 

Configuration files

All major configuration files are located in the digital-factory-config folder and also in the <digital-factory-web-app-dir>/WEB-INF/etc/ folder. If you using UNIX for the regular backup of you Jahia data, you can create a script file and run it through a Cron job. A typical example of this script is:

DAY=`date +%u`
/bin/tar cvfz /home/backup/tomcat_$DAY.tar.gz /home/jahia/tomcat/ #list of folders to copy

Note that operation has to be done on each node of a cluster. 

Restoring an environment from a backup

Restoring your database dump

Please refer your database documentation for specific instructions of how to perform a restore from a database dump.

Reinstalling Jahia

To reinstall Jahia:

  1. In the configuration wizard, instead of connecting to a new empty database, connect to your newly restored database. Clear the option to create the tables inside this database.
  2. Take care to specify the same value as you did for your previous installation for the storage of the binaries (inside the database or on the filesystem). If you do not remember, open <digital-experience-manager-web-app-dir>/WEB-INF/etc/repository/jackrabbit/repository.xml file and check the DataStore element, which could either be a DbDataStore or a FileDataStore.
  3. Do not start the application server at the end of the install process.

Applying your configurations to your new installation

Apply your backed-up configuration (usually the digital-factory-config folder content is enough) to your new installation.

Deploy your templates and modules

Deploy your templates sets and modules.

Restore the binaries stored on the filesystem

If you have chosen to store the binaries in your database, just skip this step. Copy your digital-factory-data/repository/ folder from your backup to your new installation. You will have the following structure:

repository
|_________datastore
|_________index
|_________version
|_________workspaces
| |___default
| | |____index
| | |____locks
| | |____repository.xml
| |___live
| |____index
| |____locks
| |____repository.xml
|_________indexing_configuration.xml
|_________indexing_configuration_version.xml

If you have chosen an alternative location of the datastore folder during the Jahia configuration wizard (cluster installation), please restore it at the appropriate location.

Remove the two locks files under /repostory/workspaces/default and /repository/workspaces/live directories as well as the hidden file .lock under /repository. If possible, we also recommend you to also remove the three “index” folders. Those folders store the JCR indexes, which will be regenerated at first startup if missing. Regenerating it will improve the performances. The amount of time it takes for this operation depends on the amount of data you have. If you are doing an emergency restore of a production server, you can keep the former indexes to save time.

Safe backup restore

The safe backup restore here is only relevant when you are restoring a Jahia clustered backup at another infrastructure, for example cloning a production environment to preproduction/test. It is not needed in case of a normal restore of a Jahia environment.

For details, see Safe environment clone (aka Safe backup restore) in this document.

Restart the Jahia server

For the last step, you must restart your reinstalled Jahia application.

Backing up at the system level

Export at the system level to create a complete backup. You can use the backup to restore your system.

Warning: The order of the backup steps is important to guarantee data integrity.

To export at the system level:

  1. Export Tomcat and the digital-factory-data and digital-factory-config folders.
  2. Export the datastore (only if the binary content is stored in the default file system).
  3. Export the database.

Restoring at the system level

You can restore your system from a backup.

To import at the system level:

  1.  Restore Tomcat.
  2.  Restore the digital-factory-data and digital-factory-config folders.
  3.  Restore the datastore (if applicable).
  4.  Restore the database.
  5.  Modify the datasource definition in tomcat/webapps/root/META-INF/context.xml.

In clustered instance, you may need to modify the following values in /digital-factory-config/jahia/jahia.node.properties file:

  • processingServer must be set to true on the processing server (and only on this node).
  • cluster.tcp.bindAddress must be set with the IP address where the server will listen to TCP communication.
  • cluster.tcp.bindPort must specify the port used for the server TCP socket.