Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
This page is about Backup module 2.0+, which is compatible with Magnolia 5.4.6+ .
Magnolia 5.4 ships with Backup module 1.6.x but you can choose to use the new module.
See Backup module 1.6 for earlier documentation.
The Backup module allows you to take manual and scheduled backups of content and configuration. The module backs up Magnolia configuration and all versions of content in all workspaces. Manual and automated scheduled backups can be managed in the Backup app. Backup and restore scripts are provided for more flexible backup options and for restoring Magnolia.
Old backups are not compatible
The Backup module was completely refactored and streamlined in version 2.0. Backups taken with module version 1.6 and earlier cannot be restored with the new one. The module now uses Apache's RepositoryCopier API which is independent of the underlying data storage. The new implementation respects the file store threshold.
Backup version 2.0 and higher can be used for Magnolia 5.4.6 and higher.
<dependency> <groupId>info.magnolia</groupId> <artifactId>magnolia-module-backup</artifactId> <version>2.0</version> </dependency>
The Backup app allows you to take a manual backup, schedule automatic backups and view existing backup tasks. The tool creates a backup of the entire Magnolia installation.
To take a manual backup:
Here's the structure of the backup folder.
└───<target directory> ├───repository │ ├───datastore │ ├───meta │ ├───namespaces │ ├───nodetypes │ └───privileges ├───version │ └───db └───workspaces ├───category │ └───db ├───config │ └───db ├───... └───workflow └───db ├───repository.xml
Content:
<backup folder> | |
| Subfolders containing datastore and configuration files necessary to restore the repositories. |
| Versions database. Contains versions of all versionable content from all repositories. |
| One folder per workspace. Holds all content of 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.
To schedule an automatic backup:
The tool registers an automatic backup task in the module configuration in /modules/backup/config
.
Node name | Value |
---|---|
backup | |
config | |
tasks | |
backupTask | |
automatedExecution | |
cron | 0 00 1 * * 1 |
enabled | true |
class | info.magnolia.module.backup.AutomatedBackupConfiguration |
name | backupTask |
targetPath | /magnoliaBackup |
Properties:
config | optional Module configuration node. |
| optional Tasks folder. |
| required Name of task. |
| required Automated execution node. |
| required CRON expression that sets the scheduled execution time. |
| optional, default is Enables and disables the task. |
| required AutomatedBackupConfiguration is the bean that holds the backup configuration. |
| required Task name. |
| required Path to the backup directory. |
Automatic backups include a timestamp in the backup folder.
You can view and delete scheduled automatic backups in Existing tasks.
The backup
script provides more flexibility for backing up Magnolia. Options include backing up a single workspace or file, and running a backup from a running Magnolia instance.The backup script is in the bin
folder in the Backup module bundle and needs to be run from the command line.
Usage:
./bin/backup [options]
Options:
Short version | Long version | Description |
---|---|---|
-c <arg> | --configuration <arg> | required Location of the repository configuration. |
-r <arg> | --repository <arg> | required Location of the repository to backup. |
-t <arg> | --target <arg> | required Target location for the backup. |
-mr <arg> | --maxRetries <arg> | optional Maximum number of retries when encountering an exception. |
-rt <arg> | --retryTimeout <arg> | optional Interval in seconds for retrying backup execution when an exception occurs. |
-u <context> <username:password> | --user <context> <username:password> | optional Context, username and password. Used for launching a backup from a running Magnolia instance with a given username, password and host URL.
|
-z | --zip | optional Create a compressed ZIP archive. |
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-mysql-search.xml -u http://localhost:8080 superuser:superuser
Although it is possible to backup from a running Magnolia instance, it is not a recommended 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 for more.
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 from the command line.
The restore script is meant to recreate an instance, not to patch an existing one. For it to work correctly you should clean your database schema before running it.
Run the script before starting Magnolia so that the script can re-create the repository.
To make sure the webapp
directory is properly setup before running the restore script, we recommend you take the WAR file or webapp from the bundle, add all your custom modules, startup the server once and perform the installation. Perform a backup of this new instance. After that, shutdown the server, delete the repositories
directory and run the restore as specified below.
Usage:
/restore [options]
Options:
-c | --configuration <arg> | required Location of the repository configuration.
|
-r | --repository <arg> | required Location of the repository to restore.
|
-s | --source <arg> | required Source location of the backup. |
-z | --zip | optional Restore 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
Tips
EXTRA_JVM_ARGUMENTS
variable in the script file. On a Linux server you need to grant the correct permissions to the script file in order to run it.Best practice
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 the time, perhaps do so every month or every quarter.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.
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 database persistence manager 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
The backup
command starts the backup execution process for both manual and automated requests.
The command is registered in /modules/backup/commands/backup/backup
.
Node name | Value |
---|---|
backup | |
commands | |
backup | |
backup | |
class | info.magnolia.module.backup.commands.BackupCommand |
Properties:
commands | 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 of the backup. |
| optional, default is When set to |
| optional, default is Interval in seconds for retrying backup execution when an exception occurs. |
| optional, default is Maximum number of retries when encountering an exception. |
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 stops and retries 3
times (maxRetries
default value). If the inconsistency persists the backup fails and this is 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
.
Node name | Value |
---|---|
rest-services | |
rest-endpoints | |
commands | |
enabledCommands | |
backup | |
access | |
roles | |
rest-backup | rest-backup |
catalogName | backup |
commandName | backup |
Properties:
enabledCommands | required Enabled commands node. |
| required Command node. 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 module adds the rest-back
role in the Security app.
The role allows the execution of the backup
command from a running Magnolia instance and has the following permissions:
Web access:
Permission | Path |
Get & Post | /.rest/commands/v2/backup/backup |