Backup module

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

<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:

1. Create the target backup directory on the file system. 
2. In Manual backup enter the path to your backup directory. The path must be absolute.
3. 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:

Scheduling automatic backups

To schedule an automatic backup:

1. In Automatic backup set the time, frequency, date and target directory
2. Click Schedule backup.
   

The tool registers an automatic backup task in the module configuration in /modules/backup/config. 

Properties:

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.

Usage:

./bin/backup [options]

Options: 

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

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: 

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

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.

Properties:

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.

Properties:

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:

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.