Installation

Requirements

• HumHub 1.18 or newer (tested on 1.18 and 1.19)
• PHP with the zip extension

• For the database component (backup and restore):

  • MySQL or MariaDB as the HumHub database
  • the PHP function exec() must be enabled (not listed in disable_functions)
  • the dump tool: mysqldump or mariadb-dump
  • the command line client: mysql or mariadb

  Many current systems only ship the MariaDB binaries (mariadb-dump, mariadb) without the mysql* aliases; both names are detected. The binaries are searched in PATH and in the usual installation directories. If they are missing, the settings page shows a warning. Files can still be backed up without them.

• Optional, for the compression options: PHP zlib (gzip) and the PHP bz2 extension (bzip2). The settings page only offers what is available. A backup made with bzip2 can only be restored on a server that has the bz2 extension.
• A running HumHub cron job and queue worker (see the HumHub installation guide). Backups and restores run as queue jobs.
• A backup directory that is writable by the web/PHP user, owned by it and not writable by other system users (for example mode 750; the settings page warns otherwise), and located below @runtime or outside of the web root (default: @runtime/backups). Directories that are linked into the web root (for example the uploads directory, which is a symlink in the official Docker image) count as part of the web root and are rejected.
• For restoring: every file that the restore has to change must be writable by the web/PHP user, and new files must be creatable in their directories. The restore checks every single file before it changes anything. Files that are identical to the backup are not touched, so read-only files that did not change (for example the .gitignore in a root owned directory) are no problem.

Modules

All module directories configured in moduleAutoloadPaths are backed up, except the modules shipped with HumHub (@humhub/modules) and directories that contain no modules (a directory without any sub directory, for example one that only holds a .gitignore). By default that is @app/modules.

In the official Docker image (humhub/humhub) moduleAutoloadPaths contains @app/modules (/opt/humhub/protected/modules: owned by root, only a .gitignore), /data/modules-custom, /data/modules and @humhub/modules. @app/modules is skipped because it contains no modules, so the modules of /data/modules and /data/modules-custom are backed up. A backup can only be restored on an installation that has the same module directories configured.

Signing key

Every backup is signed with an installation specific secret that is created automatically in @runtime/gm-backup/signing.key (permissions 0600). If @runtime is not persistent (for example in containers that are re-created), set a fixed key in protected/config/common.php, otherwise backups made before the re-creation can only be restored after an extra confirmation:

return [
    'params' => [
        'gmBackupSigningKey' => 'at-least-32-random-characters',
    ],
];

Keep the key secret and do not store it in the backup directory. Use a different key for each installation.

Docker

Install a MySQL/MariaDB client package in the container (for example mariadb-client) if it is not included in your image, and mount the backup directory on a volume if backups should survive container re-creation.

Setup

1. Install and enable the module in Administration → Modules.
2. Open Configure, choose the components and the backup directory and save.
3. Optional - automatic backups: enable them and choose the frequency. The module registers itself on HumHub's hourly cron event, no extra cron entry is needed.

Console

php yii gm-backup/backup/create   # queue a backup with the current settings
php yii gm-backup/backup/auto     # queue a backup if an automatic backup is due

Permissions

All actions (settings, backup, download, delete, restore) require a system administrator. The ManageModules permission is not sufficient.

Uninstalling

Disabling or uninstalling the module does not delete existing backups. They stay in the backup directory (default @runtime/backups) and contain personal data and credentials, so remove them manually when they are no longer needed.