README

Description of the module Neoskop Magnolia Backup Module.

Dependencies

Until version 0.1.0:

• Magnolia CMS >= 6.1.4

As of version 0.2.0:

• Magnolia CMS >= 6.2.13

As of version 0.3.0:

• Magnolia CMS >= 6.2.36

Installation

The module must be added as a dependency in the pom.xml of the Magnolia project:

<dependency>
    <groupId>com.github.neoskop</groupId>
    <artifactId>neoskop-magnolia-backup</artifactId>
    <version>0.4.0</version>
</dependency>

Use of the module

The module automatically exports and imports JCR workspaces for Magnolia CMS.

Currently the following functions are implemented:

• JCR export as backup with upload to a SFTP server.
• JCR import as restore with download from a SFTP server.

The necessary settings for the module can be stored via the environment variables or through the magnolia.properties.

Please note that the folder structure must already be created on the SFTP server. Therefore, for the following examples, the folders /path/to/folder/for/backup/stage and /path/to/folder/for/backup/local should be created on the SFTP server.

A brief explanation of the options:

• BACKUP_PROTOCOL: Include options for sftp and s3
• BACKUP_HOST: Host or IP address to the SFTP server, or the endpoint of your Amazon S3 bucket if s3 is selected
• BACKUP_USERNAME: Username for SFTP server (Not needed for s3)
• BACKUP_PASSWORD: Password from SFTP user (Not needed for s3)
• BACKUP_ACCESS_KEY: The access key for your Amazon S3 bucket (Not needed for sftp)
• BACKUP_SECRET_KEY: The secret access key for your Amazon S3 bucket (Not needed for sftp)
• BACKUP_REGION: The region of your Amazon S3 bucket (Not needed for sftp)
• BACKUP_BUCKET: The name of your Amazon S3 bucket (Not needed for sftp)
• BACKUP_PATH: Path to the backup directory
• BACKUP_REPOSITORIES: The workspaces to be saved can be specified via the ";" separator. If only a certain path is to be exported and imported from the workspace, it must be specified after the workspace with a ","
• BACKUP_PROJECT: Project name
• BACKUP_INSTANCE: Name of the instance, whether it is an author or public instance
• BACKUP_AUTO_ENABLED: Whether to create an automatic backup for the instance
• BACKUP_AUTO_ENVIRONMENT: Name of the current environment to be backed up automatically
• BACKUP_AUTO_CRONJOB: Cronjob string for the time of the automatic backup
• BACKUP_RESTORE_ENABLED: Whether a recovery should be performed when the module is installed on for the first time. Attention for Stage or Live environments this setting should be set to false. Only local environments should have this setting set to true
• BACKUP_RESTORE_ENVIRONMENT: Name of the environment from which a backup is to be imported if the project is started for the first time
• BACKUP_RESTORE_DURING_STARTUP: Whether a restore should be performed at the first startup and not when Magnolia has been fully loaded. This setting is required if the modules node in the configuration workspace is also to be imported. Otherwise the default value is false.
• BACKUP_ROTATION_ENABLED: Whether rotating backup copies are written in addition to the latest backup (see Backup rotation). The default value is true
• BACKUP_ROTATION_WEEKLY_DAY: Weekday on which an additional weekly rotation slot is written (MONDAY ... SUNDAY). The default value is MONDAY
• BACKUP_ROTATION_WEEKLY_COUNT: Number of weekly rotation slots before the oldest one is overwritten again. The default value is 4

Backup rotation

In addition to the latest backup, which is overwritten on every run at the fixed path used by the restore, rotating copies are stored in a rotation subfolder by default:

{environment}/{project}-{instance}.zip                      latest backup (used by restore)
{environment}/rotation/{project}-{instance}-monday.zip      daily slots, each overwritten weekly
...
{environment}/rotation/{project}-{instance}-sunday.zip
{environment}/rotation/{project}-{instance}-weekly-1.zip    weekly slots, written on BACKUP_ROTATION_WEEKLY_DAY,
...                                                         each overwritten after BACKUP_ROTATION_WEEKLY_COUNT weeks
{environment}/rotation/{project}-{instance}-weekly-4.zip

With the default settings and a daily backup cronjob this keeps the backups of the last 7 days plus the backups of the last 4 Mondays.

Please note:

• The restore always uses the latest (non-rotated) file. To restore one of the rotation slots, copy it manually to the path of the latest backup.
• For sftp the rotation subfolder is created automatically, only the environment folders have to exist (see above).
• For s3 the rotation slots are created via server-side copy, so no additional upload traffic is generated. The credentials must be allowed to perform CopyObject within the bucket.
• Reducing BACKUP_ROTATION_WEEKLY_COUNT leaves stale higher-numbered weekly-N files behind, which are never touched again and can be deleted manually.
• Backups larger than 5 GiB are not supported (limit of single-request S3 put/copy operations).

Examples for the settings

Example to pass settings via the environment variables:

BACKUP_PROTOCOL: "sftp"
BACKUP_HOST: "1.2.3.4"
BACKUP_USERNAME: "username"
BACKUP_PASSWORD: "password"
BACKUP_PATH: "/path/to/folder/for/backup"
BACKUP_REPOSITORIES: "website;users,/admin;config,/modules;config,/server;dam;"
BACKUP_PROJECT: "project-xyz"
BACKUP_INSTANCE: "author"
BACKUP_AUTO_ENABLED: "true"
BACKUP_AUTO_ENVIRONMENT: "local"
BACKUP_AUTO_CRONJOB: "0 0 3 ? * * *"
BACKUP_RESTORE_ENABLED: "true"
BACKUP_RESTORE_ENVIRONMENT: "stage"
BACKUP_RESTORE_DURING_STARTUP: "false"
BACKUP_ROTATION_ENABLED: "true"
BACKUP_ROTATION_WEEKLY_DAY: "MONDAY"
BACKUP_ROTATION_WEEKLY_COUNT: "4"

Example to pass settings via magnolia.properties file:

neoskop.magnolia.backup.server.protocol=sftp
neoskop.magnolia.backup.server.host=1.2.3.4
neoskop.magnolia.backup.server.username=username
neoskop.magnolia.backup.server.password=password
neoskop.magnolia.backup.server.path=/path/to/folder/for/backup
neoskop.magnolia.backup.repositories=website;users,/admin;config,/modules;config,/server;dam;
neoskop.magnolia.backup.project=project-xyz
neoskop.magnolia.backup.instance=author
neoskop.magnolia.backup.auto.enabled=true
neoskop.magnolia.backup.auto.environment=local
neoskop.magnolia.backup.auto.cronjob=0 0 3 ? * * *
neoskop.magnolia.backup.restore.enabled=true
neoskop.magnolia.backup.restore.environment=stage
neoskop.magnolia.backup.restore.duringStartup=false
neoskop.magnolia.backup.rotation.enabled=true
neoskop.magnolia.backup.rotation.weeklyDay=MONDAY
neoskop.magnolia.backup.rotation.weeklyCount=4