Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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.
If you are using the backup module on Magnolia 5.7.x - you must use Magnolia backup module version 2.3 or higher.
Installing
<version/>
in the dependency.<dependency> <groupId>info.magnolia</groupId> <artifactId>magnolia-module-backup</artifactId> </dependency>
Backup app
The Backup app allows you to make a manual backup, schedule automatic backups and view existing backup tasks. The tool creates a backup of the entire Magnolia installation.
Making a manual backup
To make a manual backup:
- Create the target backup directory on the file system.
- In Manual backup enter the path to your backup directory. The path must be absolute.
- Click Backup.
Here is 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.
Scheduling automatic backups
To schedule an automatic backup:
- In Automatic backup set the time, frequency, date and target directory
- Click Schedule 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
|
| required Task name. |
| required Path to the backup directory. The path must be absolute. |
Automatic backups include a timestamp in the backup folder.
Viewing existing tasks
You can view and delete scheduled automatic backups in Existing tasks.
Backup script
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.
If choose to use the script, make sure that library versions referenced by the script after the update are the same as the versions in Magnolia you are currently running.
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
|
-z | --zip | optional Create a compressed ZIP archive. |
-zp <arg> | --zipPath <arg> | required when The location for a zip backup archive. The argument should be a file with a path to it. The path provided needs to be absolute in the context of the backup module, e.g. |
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.
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 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
- 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 in order to run it. - It is not necessary to reindex your repository when the restore script is done.
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.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 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
Backup command
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. |
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 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-backup
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 |
Note that you must use POST
to send requests to the commands endpoint.
Also note that you have to define the backup command properties in the request body or predefine it in the backup command properties as described above.