From 81c2a43128cd10522f636b02d0ea4d899e4cff83 Mon Sep 17 00:00:00 2001
From: p4u1 <p4u1_f4u1@riseup.net>
Date: Mon, 8 Apr 2024 12:52:51 +0200
Subject: [PATCH] add specification

---
 Specification.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 Specification.md

diff --git a/Specification.md b/Specification.md
new file mode 100644
index 0000000..4a017f7
--- /dev/null
+++ b/Specification.md
@@ -0,0 +1,118 @@
+# 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](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1) 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"
+```