Page tree
Skip to end of metadata
Go to start of metadata

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.1. 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.

Installing

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-backup</artifactId>
  <version>2.2</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Backup app

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.

Taking a manual backup

To take a manual backup:

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

respository

Subfolders containing datastore and configuration files necessary to restore the repositories.

version

Versions database. Contains versions of all versionable content from all repositories.

workspaces

One folder per workspace. Holds all content of given workspace.

repository.xml

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:

  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

Node nameValue

 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.

tasks

optional

Tasks folder.

backupTasks

required

Name of task.

automatedExecution

required

Automated execution node.

cron

required

CRON expression that sets the scheduled execution time.

enabled

optionaldefault is false

Enables and disables the task.

class

required

AutomatedBackupConfiguration is the bean that holds the backup configuration.

name

required

Task name.

targetPath

required

Path to the backup directory.

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 in a CLI.

Usage:

./bin/backup [options]

Options: 

-c --configuration <arg> 

required

Location of the repository configuration.

-r--repository <arg>

required

Location of the repository to backup. 

-t--target <arg>

required

Target location for the backup. 

-mr--maxRetries <arg>

optional

Maximum number of retries when encountering an exception.

-rt--retryTimeout <arg> 

optional

Interval in seconds for retrying backup execution when an exception occurs. 

-u --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.

(warning) This option only works if the user has been assigned the the rest-backup role. See Backup REST service for more.

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

Restoring a backup

To restore the previously backed up data, use the restore script in the bin folder in the Backup module bundleThe 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]

Options: 

-c--configuration <arg>

required

Location of the repository configuration.

magnolia.repositories.jackrabbit.config property.

-r--repository <arg>

required

Location of the repository to restore.

magnolia.repositories.home property.

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

 backup

 

 commands

 

 backup

 

 backup

 

 class

info.magnolia.module.backup.commands.BackupCommand

Properties:

commands

optional

Commands folder.

backup

required

Backup catalog.

backup

required

Command name

class

required

BackupCommand starts the backup execution process both manual and automated requests.

repositoryPath

required, default is magnolia.repositories.home property

Location of the repository to back up.

configurationPath

required, default is magnolia.repositories.jackrabbit.config property

Location of the repository configuration.

backupLocation

required

Target location of the backup.

compression

optional, default is false

When set to true backup is compressed in a ZIP archive.

retryTimeout

optional, default is 30 seconds

Interval in seconds for retrying backup execution when an exception occurs.

maxRetries

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.

Node nameValue

 rest-services

 

 rest-endpoints

 

 commands

 

 enabledCommands

 

 backup

 

 access

 

 roles

 

 rest-backup

rest-backup

 catalogName

backup

 commandName

backup

Properties:

enabledCommands

required

Enabled commands node.

backup

required

Command node. Name is arbitrary.

access

required

Access node.

roles

required

Roles node.

rest-backup

required

Role name. Grants the rest-backup role permission to execute the command. Property name is arbitrary but the value must be a valid role name.

catalogName

required

Catalog where the command resides.

commandName

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:

PermissionPath
Get & Post/.rest/commands/v2/backup/backup
  • No labels