Backup module
Content management Bundled: DX Core
Edition |
DX Core |
License |
|
Issues |
|
Maven site |
|
Latest |
2.5.0 |
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. |
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement>
section and your webapp’s <dependencies>
section.
If the module is unbundled but the version is managed by the parent POM, add the following to your webapp’s <dependencies>
section.
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-module-backup</artifactId>
<version>2.5.0</version> (1)
</dependency>
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:
-
Create a target backup directory on the file system.
-
Under Manual backup, enter the path to your backup directory. The path must be absolute.
-
Click Backup.
Below is the structure of a backup folder once a backup is created.
└───<target directory> ├───repository │ ├───datastore │ ├───meta │ ├───namespaces │ ├───nodetypes │ └───privileges ├───version │ └───db └───workspaces ├───category │ └───db ├───config │ └───db ├───... └───workflow └───db ├───repository.xml
The following table explains the backup folder contents.
|
|
|
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:
-
Under Automatic backup, set the time, frequency and target directory.
-
Click Schedule backup.
Automatic backup tasks are registered in /modules/backup/config
.
Property | Description |
---|---|
|
optional Module configuration node. |
|
optional Tasks folder. |
|
required Task configuration node. |
|
required Automatic execution node. |
|
required CRON expression that sets the scheduled execution time. |
|
optional, default is Enables and disables the task. |
|
required info.magnolia.module.backup.AutomatedBackupConfiguration is the bean that holds the backup configuration. |
|
required Task name. |
|
required Path to the backup directory. The path must be absolute. Automatic backups include a timestamp in the backup folder. |
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.
Usage:
./bin/backup [options]
Short | Long | Description | ||
---|---|---|---|---|
|
|
required Location of the repository configuration.
|
||
|
|
required Location of the repository to back up. |
||
|
|
required Target location for the backup. |
||
|
|
optional Maximum number of retries when encountering an exception. |
||
|
|
optional Interval in seconds for retrying the backup when an exception occurs. |
||
|
|
optional Context, username and password. Used for launching a backup from a running Magnolia instance with a given username, password and host URL.
|
||
|
|
optional Creates a compressed ZIP archive. |
||
|
|
required when 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, |
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 |
---|---|---|
|
|
required Location of the repository configuration.
|
|
|
required Location of the repository to restore.
|
|
|
required Source location of the backup. |
|
|
optional Restores from a compressed ZIP archive. |
Example:
./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
|
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.
Example:
./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 command is registered in /modules/backup/commands/backup/backup
.
Property | Description |
---|---|
|
optional Commands folder. |
|
required Backup catalog. |
|
required Command name. |
|
|
|
required, default is Location of the repository to back up. |
|
required, default is Location of the repository configuration. |
|
required Target location for the backup. |
|
optional, default is When |
|
optional, default is Interval in seconds for retrying the backup when an exception occurs. |
|
optional, default is 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
.
Property | Description |
---|---|
|
required Enabled commands node. |
|
required Command node. The name is arbitrary. |
|
required Access node. |
|
required Roles node. |
|
required Role name. Grants the |
|
required Catalog where the command resides. |
|
required Command definition name. |
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:
Permission |
Path |
Get & Post |
|
You must use POST
to send requests to the
commands
endpoint.
You have to define the |