Backup module
Edition |
DX Core |
License |
|
Issues |
|
Maven site |
|
Latest |
2.4.4 |
The Backup module allows you to create manual and automatic backups of content and configuration. The module backs up Magnolia configuration and all versions of content in all workspaces. Manual and automatic backups can be managed in the Backup app. Backup and restore scripts are provided for more flexible backup and restore options.
Using the Backup module should mainly be reserved for specific cases such as cross-platform dumps (backing up on a Jackrabbit configuration and restoring on possibly another Jackrabbit configuration) and small databases. 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. |
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.4</version>
</dependency>
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.
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:
|
|
|
Subfolders containing datastore 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 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 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 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-mysql-search.xml -u http://localhost:8080 superuser:superuser
Although it is possible to back up from a running Magnolia instance, it is 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 re-create the repository.
To make sure the webapp
directory is properly 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.
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 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 BackupCommand starts the execution of both manual and automatic backups. |
|
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 |