The Backup module installs the Backup app that allows you to take a manual backup, schedule automatic backups and view scheduled backup tasks.
The Backup module ensures the proper backup of data from inside of Magnolia. This module is an alternative to file system and database backup solutions. The module provides immediate interactive backup of JackRabbit backed repositories and scheduled recurring backup support with cron-like configuration options.
The Backup module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository.
Backup is a Enterprise Edition module. It is typically already installed. Launch the Configuration app and go to
/modules/backup to check.
Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.
To install a module:
- Stop the application server.
- Copy the module JAR files into the
WEB-INF/libdirectory. The location of this directory depends on the application server.
- Restart the server.
- Go to the AdminCentral URL.
- Start the Web update process.
- Click Start up Magnolia.
Repeat the steps for each author and public instance.
To uninstall a module, remove the module JAR file from the
/WEB-INF/lib folder and restart Magnolia.
However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.
To test a module, use the embedded Derby database and take a backup of your
repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the
repositories folder from the backup. This way you can go back to square one.
We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.
Taking a manual backup
- Go to Tools > Backup.
- In Manual backup enter the target path for backup.
- Click Backup. The target ID will be created if it doesn't already exist.
The backup consists of the following files:
repoConfig.zip- all configuration files necessary to restore the repositories.
history.gz- versions of all versionable content from all repositories.
<workspace_name>.gz- one file per workspace. Holds all content of given workspace.
blobs- folder with binary data from all the workspaces.
Backup files contain confidential information on how to connect to the database. Keep your backup files in a secure location.
Scheduling automatic backups
- Go to Tools > Backup.
- In Automatic backup set the time, frequency and target directory
- Click Schedule backup.
The tool registers an automatic backup task in the module configuration in
|0 0 6 * * *|
Viewing existing tasks
Scheduled automatic backups display in a list in Existing tasks.
Restoring a backup
To restore the previously backed up data, use the
restore script in the Backup module bundle.
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.
There is no UI for running the restore script. 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, 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.
-backup <dir>. Backup folder.
-lib <dir>. Directory containing Magnolia's jar files. Default is the webapp's directory suffixed with
-propertyfiles <arg>. List of property files to load. By default, files specified in
web.xmlare used. If the properties are not specified in
web.xml, default configuration properties are used.
-saveAfter <num>. Persistence counter. The lower the number, the less memory is used and the slower the restore runs. Default value is 100.
-servername <name>. Server name. Used for dynamic property file finding.
-webapp <dir>. Webapp's root folder. Default is the current directory.
-webappname <name>. Webapp name. Used for dynamic property file finding. Default is the directory name of the webapp.
You should reindex your repository once the restore script is done since the Lucene indexer works asynchronously. Even though the restore script has completed indexing may be ongoing and incomplete.
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.
Deleting search indexes
Backup data does not contain search indexes. Indexes are created on the fly when running restore. As the indexer runs asynchronously, the indexing may still be in progress when restore is done. For this reason, we recommend that you remove all indexes before starting up a restored instance. This ensures that indexes are freshly generated on startup (Note that this process can take a couple of minutes). To remove indexes just delete all
index folders from the workspaces. On unix systems you can do so by executing
rm -rf repositories/magnolia/workspaces/*/index.
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/restore to migrate data to another persistence manager and to another database.
To change the persistence manager configuration to which the
restore script restores the database:
- Unzip all entries from
repoConfig.zip. You can find this file inside each backup folder.
- Change the persistence manager configuration in each file.
- Zip the files.
Run the restore.
This step is not necessary if you performed a backup of the new instance. Get the
repoConfig.zipfile from that backup and run the restore script