Backup module
Edition | DX Core |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
2.4.1 |
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.
Installing with maven
Maven is the easiest way to install the module. Add the following to your bundle:
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-module-backup</artifactId>
<version>2.4.1</version>
</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
.
Property | Description |
---|---|
|
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. The path must be absolute. Automatic backups include a timestamp in the backup folder. |
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 in a CLI.
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]
Short | Long | Description | ||
---|---|---|---|---|
|
|
required Location of the repository configuration. |
||
|
|
required Location of the repository to backup. |
||
|
|
required Target location for the backup. |
||
|
|
optional Maximum number of retries when encountering an exception. |
||
|
|
optional Interval in seconds for retrying backup execution when an exception occurs. |
||
|
|
optional Context, username and password. Used for launching a backup from a
running Magnolia instance
|
||
|
|
optional Create a compressed ZIP archive. |
||
|
|
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 in a CLI.
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]
Short | Long | Description |
---|---|---|
|
|
required Location of the repository configuration.
|
|
|
required Location of the repository to restore.
|
|
|
required Source location of the backup. |
|
|
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
|
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 command is registered in /modules/backup/commands/backup/backup
.
Property | Description |
---|---|
|
optional Commands folder. |
|
required Backup catalog. |
|
required Command name |
|
required BackupCommand starts the backup execution process both manual and automated requests. |
|
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 `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 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
.
Property | Description |
---|---|
|
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 The role allows the execution of the |
- Web access
Permission |
Path |
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 or predefine it in the backup command properties as described above. |