Backup module

Content management Bundled: Extension


DX Core




Maven site



The Backup module allows you to create manual and automatic content and configuration data backups. The module backs up the configuration of the respective Magnolia instance on which it runs and all versions of content stored in all its workspaces.

You can manage both manual and automatic backups in the Backup app. Scripts can back up and restore content and configuration data flexibly by specifying various backup and restore options.

Using the Backup module should mainly be reserved for specific cases such as cross-platform dumps and small databases. A cross-platform dump might be backing up on a Jackrabbit configuration and restoring on possibly another Jackrabbit configuration.

For production environments, we recommend you use both database tools and file system copies (the contents of any file stored and optionally Lucene indexes) to have consistent and transaction-safe backups.

Most of your content is stored in a database, and you can use database tools to back up and restore your JCR content. However, some high-level steps to remember when backing up your content are outlined here.

Backup app

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

  <version>2.5.1</version> (1)
1 Should you need to specify the module version, do it using <version>.

Backup app

The Backup app allows you to create manual backups, schedule automatic backups and manage existing backup tasks. The app creates a backup of the entire Magnolia installation.

Creating manual backups

To create a manual backup:

  1. Create a target backup directory on the file system.

  2. Under Manual backup, enter the path to your backup directory. The path must be absolute.

  3. Click Backup.

Manual backup

Below is the structure of a backup folder once a backup is created.

└───<target directory>
    │   ├───datastore
    │   ├───meta
    │   ├───namespaces
    │   ├───nodetypes
    │   └───privileges
    │   └───db
        │   └───db
        │   └───db

The following table explains the backup folder contents.

<backup folder>


Subfolders containing data store and configuration files necessary to restore the repositories.


Version database. Contains versions of all versionable content from all repositories.


One folder per workspace. Holds all content of a given workspace.


Repository configuration file.

Backup files contain confidential information on how to connect to the database. Keep your backup files in a secure location.

Scheduling automatic backups

To schedule an automatic backup:

  1. Under Automatic backup, set the time, frequency and target directory.

  2. Click Schedule backup.

Automatic backup

Automatic backup tasks are registered in /modules/backup/config.

Backup module configuration

Property Description



Module configuration node.



Tasks folder.



Task configuration node.



Automatic execution node.



CRON expression that sets the scheduled execution time.


optional, default is false

Enables and disables the task.



info.magnolia.module.backup.AutomatedBackupConfiguration is the bean that holds the backup configuration.



Task name.



Path to the backup directory. The path must be absolute.

Automatic backups include a timestamp in the backup folder.

Managing existing tasks

Under Existing tasks, you can view and delete scheduled automatic backups.

Existing tasks

Backup script

For backing up Magnolia, the backup script provides more flexibility and options, such as launching a backup from a running Magnolia instance.

The script is in the bin folder in the Backup module bundle and needs to be run in a CLI.

If you choose to use the script, make sure that the library versions in the target webapp after a restoration update are the same as those in the Magnolia instance you are currently running.


./bin/backup [options]
Short Long Description

-c <arg>

--configuration <arg>


Location of the repository configuration.

By default, Derby is the database configured out of the box. Several configuration files are included in your installation’s apache-tomcat/webapps/magnoliaAuthor/WEB-INF/config/repo-conf folder. Make sure you specify the file that best fits your database, for example, jackrabbit-bundle-derby-search.xml for Derby.

-r <arg>

--repository <arg>


Location of the repository to back up.

-t <arg>

--target <arg>


Target location for the backup.

-mr <arg>

--maxRetries <arg>


Maximum number of retries when encountering an exception.

-rt <arg>

--retryTimeout <arg>


Interval in seconds for retrying the backup when an exception occurs.

-u <context> <username:password>

--user <context> <username:password>


Context, username and password. Used for launching a backup from a running Magnolia instance with a given username, password and host URL.

This option only works if the user has been assigned the rest-backup role. See Backup REST service.




Creates a compressed ZIP archive.

-zp <arg>

--zipPath <arg>

required when -z is used

Location for a zip backup archive. The argument must be a file with a path.

The path must be absolute in the context of the Backup module (for example, -z -zp /tmp/

Example: Launching a backup from a running Magnolia instance.

./bin/backup -t /tmp/backup/backup-some/01 -r /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/repositories/magnolia -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml -u http://localhost:8080 superuser:superuser

Although it’s possible to back up from a running Magnolia instance, it’s not recommended as a best practice. To ensure stability and prevent potential inconsistencies caused by nodes being published (versioned) during the backup process, avoid this option if possible. See Backup REST service.

Restoring a backup

To restore the previously backed up data, use the restore script in the bin folder in the Backup module bundle. The restore script needs to be run in a CLI.

The restore script is meant to re-create an instance, not to patch an existing one.

For it to work correctly, you need to:

  • Clean your database schema before running the script.

  • Run the script before starting Magnolia so that the script can recreate the repository.

To make sure the webapp directory is set up before running the restore script, we recommend you take the WAR file or webapp from the bundle, add all your custom modules, start up the server once and perform the installation. Create a backup of this new instance before shutting down the server, deleting the repositories directory and running the restore as specified below.

/restore [options]
Short Long Description


--configuration <arg>


Location of the repository configuration.

magnolia.repositories.jackrabbit.config property.


--repository <arg>


Location of the repository to restore.

magnolia.repositories.home property followed by the repository name (default: magnolia).


--source <arg>


Source location of the backup.




Restores from a compressed ZIP archive.


./bin/restore -r /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/repositories/magnolia -s /magnoliaBackups/Sept2016/01 -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-config/jackrabbit-bundle-mysql-search.xml
  • Assign the restore script more memory by changing the EXTRA_JVM_ARGUMENTS variable in the script file. On a Linux server, you need to grant the correct permissions to the script file to run it.

  • It’s not necessary to reindex your repository when you run the restore script.

For safety reasons, run the restore from time to time on a test system to verify the validity of the backup files. Depending on the amount of data changed over time, do this every month or every quarter.

Database size

During restore, all entries are reinserted into the database sequentially. This ensures that the restored database is not fragmented and is slightly smaller than the equivalent database before backup.

Changing persistence managers

You can use backup and restore to migrate data to another persistence manager and to another database. For example, you can change from Derby to MySQL.

To change persistence managers, use the -c <arg> (--configuration <arg>) option to point to the new configuration.


./bin/restore -c /Users/Name/Workspace/dev-project/magnolia-dev-webapp/target/magnolia-dev-webapp-1.0/WEB-INF/config/repo-config/jackrabbit-bundle-mysql-search.xml

Backup command

The backup command starts the execution of both manual and automatic backups.

The command is registered in /modules/backup/commands/backup/backup.

Backup command

Property Description



Commands folder.



Backup catalog.



Command name.



info.magnolia.module.backup.commands.BackupCommand starts the execution of both manual and automatic backups.


required, default is magnolia.repositories.home

Location of the repository to back up.


required, default is magnolia.repositories.jackrabbit.config

Location of the repository configuration.



Target location for the backup.


optional, default is false

When true, the backup is compressed in a ZIP archive.


optional, default is 30

Interval in seconds for retrying the backup when an exception occurs.


optional, default is 3

Maximum number of retries when encountering an exception.

Backup REST service

The backup command is executed with a REST call. This allows observation of the mgnlVersion workspace and prevents potential inconsistencies if a node is published (versioned) during the backup process. If an inconsistency is detected, the backup will stop and retry 3 times (the default value for maxRetries). If the inconsistency persists, the backup will fail and this will be logged to the user.

The backup command is enabled as a REST endpoint in the REST Services module in /modules/rest-services/rest-endpoints/commands/enabledCommands/backup.

Backup REST

Property Description



Enabled commands node.



Command node. The name is arbitrary.



Access node.



Roles node.



Role name. Grants the rest-backup role permission to execute the command. The property name is arbitrary, but the value must be a valid role name.



Catalog where the command resides.



The Backup module adds the rest-backup role to the Security app. The role allows the execution of the backup command from a running Magnolia instance and has the following web access permission:



Get & Post


You must use POST to send requests to the commands endpoint.

You have to define the backup command properties in the request body as described above.


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.