docs.coopcloud.tech/Specification.md

Specification

Summary

Creating automated backups of docker swarm services is an often needed task. This specification describes how backups can be configured via service labels in a standardised way.

Requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC-2119].

When backing up a docker stack you MUST first check if the backupbot.backup. It MUST be set to true, for the backup to happen.

Backup

To enable backups for a docker stack, the backupbot.backup=true label MUST be on any of its services. It SHOULD be declared on the first service. A backupbot.backup.pre-hook MAY be set on a service. When set the command MUST be executed inside the running container of the service before backup up files. By default all volumes MUST be backed up. A volume MAY be excluded from backing up when backupbot.backup.volumes.{volume_name}=false is set, where {volume_name} is the name of the volume. By default all files MUST be backed up on a volume. backupbot.backup.volumes.{volume_name}.path MAY be set to limit the paths for that volume. The value MUST be a valid path relative to the volume root. It MAY contain multiple paths which get seperated by a comma. A backupbot.backup.post-hook MAY be set on a service. When set the command MUST be executed inside the running container of the service after backing up all files. A backup implementation SHOULD provide the backup of one or multiple stacks in a .tar.gz format.

Restore

A backupbot.restore.pre-hook MAY be set on a service. When set the command MUST be executed inside the running container of the service before restoring backup files. By default all files MUST be restored into their volume. A volume or path MAY be excluded from restoring. A backupbot.restore.post-hook MAY be set on a service. When set the command MUST be executed inside the running container of the service after restoring backup files.

Labels

backupbot.backup

Type: boolean Default: false Description: Enables backupbot for this compose stack. The labe should be added to the main service of the compose stack.

Example:

backupbot.backup: true

backupbot.backup.volumes.{volume_name}

Type: boolean Default: true Description: When set to false the volume is excluded from backups.

Example:

backupbot.backup.volumes.{volume_name}: false

backupbot.backup.volumes.{volume_name}.path

Type: string Default: "" Description: A comma seperated list of paths. When one or more paths are set, it only backups up those on the given volume instead of the whole volume.

Example:

backupbot.backup.volumes.{volume_name}.path: '/var/lib/mariadb/dump.sql.gz'

backupbot.backup.pre-hook

Type: string Default: "" Description: A command, that gets executed before the files are backed up.

Example:

backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_password)" -f /volume_path/dump.db'

backupbot.backup.post-hook

Type: string Default: "" Description: A command, that gets executed after the files are backuped.

Example:

backupbot.backup.post-hook: "rm -rf /volume_path/dump.db"

backupbot.restore.pre-hook

Type: string Default: "" Description: A command, that gets executed before the files are restored.

Example:

backupbot.restore.pre-hook: "lock db"

backupbot.restore.post-hook

Type: string Default: "" Description: A command, that gets executed after the files are restored.

Example:

backupbot.restore.post-hook: "sqldump dump.sql && unlock db && rm dump.sql"