Docs site (#269)

* Set up documentation site using jekyll

* Add workflow for deploying docs

* Ini formatting is hard to read

* Add instructions on how to run docs locally

* Work through docs

* Remove content from README

* Miscellaneous fixes

* Fix artifact upload

docs/how-tos/automatically-prune-old-backups.md

@@ -0,0 +1,34 @@
+---
+title: Automatically prune old backups
+layout: default
+parent: How Tos
+nav_order: 3
+---
+
+# Automatically prune old backups
+
+When `BACKUP_RETENTION_DAYS` is configured, the command will check if there are any archives in the remote storage backend(s) or local archive that are older than the given retention value and rotate these backups away.
+
+{: .note }
+Be aware that this mechanism looks at __all files in the target bucket or archive__, which means that other files that are older than the given deadline are deleted as well.
+In case you need to use a target that cannot be used exclusively for your backups, you can configure `BACKUP_PRUNING_PREFIX` to limit which files are considered eligible for deletion:
+
+```yml
+version: '3'
+
+services:
+  # ... define other services using the `data` volume here
+  backup:
+    image: offen/docker-volume-backup:v2
+    environment:
+      BACKUP_FILENAME: backup-%Y-%m-%dT%H-%M-%S.tar.gz
+      BACKUP_PRUNING_PREFIX: backup-
+      BACKUP_RETENTION_DAYS: '7'
+    volumes:
+      - ${HOME}/backups:/archive
+      - data:/backup/my-app-backup:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+volumes:
+  data:
+```

docs/how-tos/define-different-retention-schedules.md

@@ -0,0 +1,40 @@
+---
+title: Define different retention schedules
+layout: default
+parent: How Tos
+nav_order: 9
+---
+
+# Define different retention schedules
+
+If you want to manage backup retention on different schedules, the most straight forward approach is to define a dedicated configuration for retention rule using a different prefix in the `BACKUP_FILENAME` parameter and then run them on different cron schedules.
+
+For example, if you wanted to keep daily backups for 7 days, weekly backups for a month, and retain monthly backups forever, you could create three configuration files and mount them into `/etc/dockervolumebackup/conf.d`:
+
+```ini
+# 01daily.conf
+BACKUP_FILENAME="daily-backup-%Y-%m-%dT%H-%M-%S.tar.gz"
+# run every day at 2am
+BACKUP_CRON_EXPRESSION="0 2 * * *"
+BACKUP_PRUNING_PREFIX="daily-backup-"
+BACKUP_RETENTION_DAYS="7"
+```
+
+```ini
+# 02weekly.conf
+BACKUP_FILENAME="weekly-backup-%Y-%m-%dT%H-%M-%S.tar.gz"
+# run every monday at 3am
+BACKUP_CRON_EXPRESSION="0 3 * * 1"
+BACKUP_PRUNING_PREFIX="weekly-backup-"
+BACKUP_RETENTION_DAYS="31"
+```
+
+```ini
+# 03monthly.conf
+BACKUP_FILENAME="monthly-backup-%Y-%m-%dT%H-%M-%S.tar.gz"
+# run every 1st of a month at 4am
+BACKUP_CRON_EXPRESSION="0 4 1 * *"
+```
+
+{: .note }
+While it's possible to define colliding cron schedules for each of these configurations, you might need to adjust the value for `LOCK_TIMEOUT` in case your backups are large and might take longer than an hour.

docs/how-tos/encrypt-backups-using-gpg.md

@@ -0,0 +1,17 @@
+---
+title: Encrypt backups using GPG
+layout: default
+parent: How Tos
+nav_order: 7
+---
+
+# Encrypt backups using GPG
+
+The image supports encrypting backups using GPG out of the box.
+In case a `GPG_PASSPHRASE` environment variable is set, the backup archive will be encrypted using the given key and saved as a `.gpg` file instead.
+
+Assuming you have `gpg` installed, you can decrypt such a backup using (your OS will prompt for the passphrase before decryption can happen):
+
+```console
+gpg -o backup.tar.gz -d backup.tar.gz.gpg
+```

docs/how-tos/handle-file-uploads-using-third-party-tools.md

@@ -0,0 +1,44 @@
+---
+title: Handle file uploads using third party tools
+layout: default
+parent: How Tos
+nav_order: 10
+---
+
+# Handle file uploads using third party tools
+
+If you want to use an unsupported storage backend, or want to use a third party (e.g. rsync, rclone) tool for file uploads, you can build a Docker image containing the required binaries off this one, and call through to these in lifecycle hooks.
+
+For example, if you wanted to use `rsync`, define your Docker image like this:
+
+```Dockerfile
+FROM offen/docker-volume-backup:v2
+
+RUN apk add rsync
+```
+
+Using this image, you can now omit configuring any of the supported storage backends, and instead define your own mechanism in a `docker-volume-backup.copy-post` label:
+
+```yml
+version: '3'
+
+services:
+  backup:
+    image: your-custom-image
+    restart: always
+    environment:
+      BACKUP_FILENAME: "daily-backup-%Y-%m-%dT%H-%M-%S.tar.gz"
+      BACKUP_CRON_EXPRESSION: "0 2 * * *"
+    labels:
+      - docker-volume-backup.copy-post=/bin/sh -c 'rsync $$COMMAND_RUNTIME_ARCHIVE_FILEPATH /destination'
+    volumes:
+      - app_data:/backup/app_data:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+
+  # other services defined here ...
+volumes:
+  app_data:
+```
+
+{: .note }
+Commands will be invoked with the filepath of the tar archive passed as `COMMAND_RUNTIME_BACKUP_FILEPATH`.

docs/how-tos/index.md

@@ -0,0 +1,8 @@
+---
+title: How Tos
+layout: default
+nav_order: 3
+has_children: true
+---
+
+## How Tos

docs/how-tos/manual-trigger.md

@@ -0,0 +1,20 @@
+---
+title: Trigger a backp manually
+layout: default
+parent: How Tos
+nav_order: 8
+---
+
+# Trigger a backup manually
+
+You can manually trigger a backup run outside of the defined cron schedule by executing the `backup` command inside the container:
+
+```console
+docker exec <container_ref> backup
+```
+
+If the container is configured to run multiple schedules, you can source the respective conf file before invoking the command:
+
+```console
+docker exec <container_ref> /bin/sh -c 'set -a; source /etc/dockervolumebackup/conf.d/myconf.env; set +a && backup'
+```

docs/how-tos/replace-deprecated-backup-from-snapshot.md

@@ -0,0 +1,37 @@
+---
+title: Replace deprecated BACKUP_FROM_SNAPSHOT usage
+layout: default
+parent: How Tos
+nav_order: 16
+---
+
+# Replace deprecated `BACKUP_FROM_SNAPSHOT` usage
+
+Starting with version 2.15.0, the `BACKUP_FROM_SNAPSHOT` feature has been deprecated.
+If you need to prepare your sources before the backup is taken, use `archive-pre`, `archive-post` and an intermediate volume:
+
+```yml
+version: '3'
+
+services:
+  my_app:
+    build: .
+    volumes:
+      - data:/var/my_app
+      - backup:/tmp/backup
+    labels:
+      - docker-volume-backup.archive-pre=cp -r /var/my_app /tmp/backup/my-app
+      - docker-volume-backup.archive-post=rm -rf /tmp/backup/my-app
+
+  backup:
+    image: offen/docker-volume-backup:v2
+    environment:
+      BACKUP_SOURCES: /tmp/backup
+    volumes:
+      - backup:/backup:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+volumes:
+  data:
+  backup:
+```

docs/how-tos/replace-deprecated-exec-labels.md

@@ -0,0 +1,23 @@
+---
+title: Replace deprecated exec-pre and exec-post labels
+layout: default
+parent: How Tos
+nav_order: 17
+---
+
+# Replace deprecated `exec-pre` and `exec-post` labels
+
+Version 2.19.0 introduced the option to run labeled commands at multiple points in time during the backup lifecycle.
+In order to be able to use more obvious terminology in the new labels, the existing `exec-pre` and `exec-post` labels have been deprecated.
+If you want to emulate the existing behavior, all you need to do is change `exec-pre` to `archive-pre` and `exec-post` to `archive-post`:
+
+```diff
+    labels:
+-     - docker-volume-backup.exec-pre=cp -r /var/my_app /tmp/backup/my-app
++     - docker-volume-backup.archive-pre=cp -r /var/my_app /tmp/backup/my-app
+-     - docker-volume-backup.exec-post=rm -rf /tmp/backup/my-app
++     - docker-volume-backup.archive-post=rm -rf /tmp/backup/my-app
+```
+
+The `EXEC_LABEL` setting and the `docker-volume-backup.exec-label` label stay as is.
+Check the additional documentation on running commands during the backup lifecycle to find out about further possibilities.

docs/how-tos/restore-volumes-from-backup.md

@@ -0,0 +1,46 @@
+---
+title: Restore volumes from a backup
+layout: default
+parent: How Tos
+nav_order: 6
+---
+
+# Restore volumes from a backup
+
+In case you need to restore a volume from a backup, the most straight forward procedure to do so would be:
+
+- Stop the container(s) that are using the volume
+- Untar the backup you want to restore
+  ```console
+  tar -C /tmp -xvf  backup.tar.gz
+  ```
+- Using a temporary once-off container, mount the volume (the example assumes it's named `data`) and copy over the backup. Make sure you copy the correct path level (this depends on how you mount your volume into the backup container), you might need to strip some leading elements
+  ```console
+  docker run -d --name temp_restore_container -v data:/backup_restore alpine
+  docker cp /tmp/backup/data-backup temp_restore_container:/backup_restore
+  docker stop temp_restore_container
+  docker rm temp_restore_container
+  ```
+- Restart the container(s) that are using the volume
+
+Depending on your setup and the application(s) you are running, this might involve other steps to be taken still.
+
+---
+
+If you want to rollback an entire volume to an earlier backup snapshot (recommended for database volumes):
+
+- Trigger a manual backup if necessary (see `Manually triggering a backup`).
+- Stop the container(s) that are using the volume.
+- If volume was initially created using docker-compose, find out exact volume name using:
+  ```console
+  docker volume ls
+  ```
+- Remove existing volume (the example assumes it's named `data`):
+  ```console
+  docker volume rm data
+  ```
+- Create new volume with the same name and restore a snapshot:
+  ```console
+  docker run --rm -it -v data:/backup/my-app-backup -v /path/to/local_backups:/archive:ro alpine tar -xvzf /archive/full_backup_filename.tar.gz
+  ```
+- Restart the container(s) that are using the volume.

docs/how-tos/run-custom-commands.md

@@ -0,0 +1,87 @@
+---
+title: Run custom commands during the backup lifecycle
+layout: default
+nav_order: 5
+parent: How Tos
+---
+
+# Run custom commands during the backup lifecycle
+
+In certain scenarios it can be required to run specific commands before and after a backup is taken (e.g. dumping a database).
+When mounting the Docker socket into the `docker-volume-backup` container, you can define pre- and post-commands that will be run in the context of the target container (it is also possible to run commands inside the `docker-volume-backup` container itself using this feature).
+Such commands are defined by specifying the command in a `docker-volume-backup.[step]-[pre|post]` label where `step` can be any of the following phases of a backup lifecycle:
+
+- `archive` (the tar archive is created)
+- `process` (the tar archive is processed, e.g. encrypted - optional)
+- `copy` (the tar archive is copied to all configured storages)
+- `prune` (existing backups are pruned based on the defined ruleset - optional)
+
+Taking a database dump using `mysqldump` would look like this:
+
+```yml
+version: '3'
+
+services:
+  # ... define other services using the `data` volume here
+  database:
+    image: mariadb
+    volumes:
+      - backup_data:/tmp/backups
+    labels:
+      - docker-volume-backup.archive-pre=/bin/sh -c 'mysqldump --all-databases > /backups/dump.sql'
+
+volumes:
+  backup_data:
+```
+
+{: .note }
+Due to Docker limitations, you currently cannot use any kind of redirection in these commands unless you pass the command to `/bin/sh -c` or similar.
+I.e. instead of using `echo "ok" > ok.txt` you will need to use `/bin/sh -c 'echo "ok" > ok.txt'`.
+
+If you need fine grained control about which container's commands are run, you can use the `EXEC_LABEL` configuration on your `docker-volume-backup` container:
+
+```yml
+version: '3'
+
+services:
+  database:
+    image: mariadb
+    volumes:
+      - backup_data:/tmp/backups
+    labels:
+      - docker-volume-backup.archive-pre=/bin/sh -c 'mysqldump --all-databases > /tmp/volume/dump.sql'
+      - docker-volume-backup.exec-label=database
+
+  backup:
+    image: offen/docker-volume-backup:v2
+    environment:
+      EXEC_LABEL: database
+    volumes:
+      - data:/backup/dump:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+volumes:
+  backup_data:
+```
+
+
+The backup procedure is guaranteed to wait for all `pre` or `post` commands to finish before proceeding.
+However, there are no guarantees about the order in which they are run, which could also happen concurrently.
+
+By default the backup command is executed by the user provided by the container's image.
+It is possible to specify a custom user that is used to run commands in dedicated labels with the format `docker-volume-backup.[step]-[pre|post].user`:
+
+```yml
+version: '3'
+
+services:
+  gitea:
+    image: gitea/gitea
+    volumes:
+      - backup_data:/tmp
+    labels:
+      - docker-volume-backup.archive-pre.user=git
+      - docker-volume-backup.archive-pre=/bin/bash -c 'cd /tmp; /usr/local/bin/gitea dump -c /data/gitea/conf/app.ini -R -f dump.zip'
+```
+
+Make sure the user exists and is present in `passwd` inside the target container.

docs/how-tos/run-multiple-schedules.md

@@ -0,0 +1,52 @@
+---
+title: Run multiple backup schedules in the same container
+layout: default
+parent: How Tos
+nav_order: 11
+---
+
+# Run multiple backup schedules in the same container
+
+Multiple backup schedules with different configuration can be configured by mounting an arbitrary number of configuration files (using the `.env` format) into `/etc/dockervolumebackup/conf.d`:
+
+```yml
+version: '3'
+
+services:
+  # ... define other services using the `data` volume here
+  backup:
+    image: offen/docker-volume-backup:v2
+    volumes:
+      - data:/backup/my-app-backup:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./configuration:/etc/dockervolumebackup/conf.d
+
+volumes:
+  data:
+```
+
+A separate cronjob will be created for each config file.
+If a configuration value is set both in the global environment as well as in the config file, the config file will take precedence.
+The `backup` command expects to run on an exclusive lock, so in case you provide the same or overlapping schedules in your cron expressions, the runs will still be executed serially, one after the other.
+The exact order of schedules that use the same cron expression is not specified.
+In case you need your schedules to overlap, you need to create a dedicated container for each schedule instead.
+When changing the configuration, you currently need to manually restart the container for the changes to take effect.
+
+Set `BACKUP_SOURCES` for each config file to control which subset of volume mounts gets backed up:
+
+```yml
+# With a volume configuration like this:
+volumes:
+  - /var/run/docker.sock:/var/run/docker.sock:ro
+  - ./configuration:/etc/dockervolumebackup/conf.d
+  - app1_data:/backup/app1_data:ro
+  - app2_data:/backup/app2_data:ro
+```
+
+```ini
+# In the 1st config file:
+BACKUP_SOURCES=/backup/app1_data
+
+# In the 2nd config file:
+BACKUP_SOURCES=/backup/app2_data
+```

docs/how-tos/set-container-timezone.md

@@ -0,0 +1,27 @@
+---
+title: Set the timezone the container runs in
+layout: default
+parent: How Tos
+nav_order: 8
+---
+
+# Set the timezone the container runs in
+
+By default a container based on this image will run in the UTC timezone.
+As the image is designed to be as small as possible, additional timezone data is not included.
+In case you want to run your cron rules in your local timezone (respecting DST and similar), you can mount your Docker host's `/etc/timezone` and `/etc/localtime` in read-only mode:
+
+```yml
+version: '3'
+
+services:
+  backup:
+    image: offen/docker-volume-backup:v2
+    volumes:
+      - data:/backup/my-app-backup:ro
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+
+volumes:
+  data:
+```

docs/how-tos/set-up-drobox.md

@@ -0,0 +1,37 @@
+---
+title: Set up Dropbox storage backend
+layout: default
+parent: How Tos
+nav_order: 12
+---
+
+# Set up Dropbox storage backend
+
+## Acquiring authentication tokens
+
+1. Create a new Dropbox App in the [App Console](https://www.dropbox.com/developers/apps)
+2. Open your new Dropbox App and set `DROPBOX_APP_KEY` and `DROPBOX_APP_SECRET` in your environment (e.g. docker-compose.yml) accordingly
+3. Click on `Permissions` in your app and make sure, that the following permissions are cranted (or more):
+  - `files.metadata.write`
+  - `files.metadata.read`
+  - `files.content.write`
+  - `files.content.read`
+4. Replace APPKEY in `https://www.dropbox.com/oauth2/authorize?client_id=APPKEY&token_access_type=offline&response_type=code` with the app key from step 2
+5. Visit the URL and confirm the access of your app. This gives you an `auth code` -> save it somewhere!
+6. Replace AUTHCODE, APPKEY, APPSECRET accordingly and perform the request:
+```
+curl https://api.dropbox.com/oauth2/token \
+    -d code=AUTHCODE \
+    -d grant_type=authorization_code \
+    -d client_id=APPKEY \
+    -d client_secret=APPSECRET
+```
+7. Execute the request. You will get a JSON formatted reply. Use the value of the `refresh_token` for the last environment variable `DROPBOX_REFRESH_TOKEN`
+8. You should now have `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET` and `DROPBOX_REFRESH_TOKEN` set. These don't expire.
+
+Note: Using the "Generated access token" in the app console is not supported, as it is only very short lived and therefore not suitable for an automatic backup solution. The refresh token handles this automatically - the setup procedure above is only needed once.
+
+## Other parameters
+
+Important: If you chose `App folder` access during the creation of your Dropbox app in step 1 above, you can only write in the app's directory!
+This means, that `DROPBOX_REMOTE_PATH` must start with e.g. `/Apps/YOUR_APP_NAME` or `/Apps/YOUR_APP_NAME/some_sub_dir`

docs/how-tos/set-up-notifications.md

@@ -0,0 +1,125 @@
+---
+title: Receive notifications
+layout: default
+nav_order: 4
+parent: How Tos
+---
+
+# Receive notifications
+
+## Send email notifications on failed backup runs
+
+To send out email notifications on failed backup runs, provide SMTP credentials, a sender and a recipient:
+
+```yml
+version: '3'
+
+services:
+  backup:
+    image: offen/docker-volume-backup:v2
+    environment:
+      # ... other configuration values go here
+      NOTIFICATION_URLS=smtp://me:secret@smtp.example.com:587/?fromAddress=no-reply@example.com&toAddresses=you@example.com
+```
+
+Notification backends other than email are also supported.
+Refer to the documentation of [shoutrrr][shoutrrr-docs] to find out about options and configuration.
+
+[shoutrrr-docs]: https://containrrr.dev/shoutrrr/0.7/services/overview/
+
+{: .note }
+If you also want notifications on successful executions, set `NOTIFICATION_LEVEL` to `info`.
+
+## Customize notifications
+
+The title and body of the notifications can be tailored to your needs using [Go templates](https://pkg.go.dev/text/template).
+Template sources must be mounted inside the container in `/etc/dockervolumebackup/notifications.d/`: any file inside this directory will be parsed.
+
+```yml
+services:
+  backup:
+    image: offen/docker-volume-backup:v2
+    volumes:
+      - ./customized.template:/etc/dockervolumebackup/notifications.d/01.template
+```
+
+The files have to define [nested templates](https://pkg.go.dev/text/template#hdr-Nested_template_definitions) in order to override the original values. An example:
+
+{% raw %}
+```
+{{ define "title_success" -}}
+✅ Successfully ran backup {{ .Config.BackupStopContainerLabel }}
+{{- end }}
+
+{{ define "body_success" -}}
+▶️ Start time: {{ .Stats.StartTime | formatTime }}
+⏹️ End time: {{ .Stats.EndTime | formatTime }}
+⌛ Took time: {{ .Stats.TookTime }}
+🛑 Stopped containers: {{ .Stats.Containers.Stopped }}/{{ .Stats.Containers.All }} ({{ .Stats.Containers.StopErrors }} errors)
+⚖️ Backup size: {{ .Stats.BackupFile.Size | formatBytesBin }} / {{ .Stats.BackupFile.Size | formatBytesDec }}
+🗑️ Pruned backups: {{ .Stats.Storages.Local.Pruned }}/{{ .Stats.Storages.Local.Total }} ({{ .Stats.Storages.Local.PruneErrors }} errors)
+{{- end }}
+```
+{% endraw %}
+
+Template names that can be overridden are:
+  - `title_success` (the title used for a successful execution)
+  - `body_success` (the body used for a successful execution)
+  - `title_failure` (the title used for a failed execution)
+  - `body_failure` (the body used for a failed execution)
+
+## Notification templates reference
+
+Configuration, data about the backup run and helper functions will be passed to these templates, this page documents them fully.
+
+### Data
+
+Here is a list of all data passed to the template:
+
+* `Config`: this object holds the configuration that has been passed to the script. The field names are the name of the recognized environment variables converted in PascalCase. (e.g. `BACKUP_STOP_CONTAINER_LABEL` becomes `BackupStopContainerLabel`)
+* `Error`: the error that made the backup fail. Only available in the `title_failure` and `body_failure` templates
+* `Stats`: objects that holds stats regarding script execution. In case of an unsuccessful run, some information may not be available.
+  * `StartTime`: time when the script started execution
+  * `EndTime`: time when the backup has completed successfully (after pruning)
+  * `TookTime`: amount of time it took for the backup to run. (equal to `EndTime - StartTime`)
+  * `LockedTime`: amount of time it took for the backup to acquire the exclusive lock
+  * `LogOutput`: full log of the application
+  * `Containers`: object containing stats about the docker containers
+    * `All`: total number of containers
+    * `ToStop`: number of containers matched by the stop rule
+    * `Stopped`: number of containers successfully stopped
+    * `StopErrors`: number of containers that were unable to be stopped (equal to `ToStop - Stopped`)
+  * `BackupFile`: object containing information about the backup file
+    * `Name`: name of the backup file (e.g. `backup-2022-02-11T01-00-00.tar.gz`)
+    * `FullPath`: full path of the backup file (e.g. `/archive/backup-2022-02-11T01-00-00.tar.gz`)
+    * `Size`: size in bytes of the backup file
+  * `Storages`: object that holds stats about each storage
+    * `Local`, `S3`, `WebDAV`, `Azure`, `Dropbox` or `SSH`:
+      * `Total`: total number of backup files
+      * `Pruned`: number of backup files that were deleted due to pruning rule
+      * `PruneErrors`: number of backup files that were unable to be pruned
+
+### Functions
+
+Some formatting and helper functions are also available:
+
+* `formatTime`: formats a time object using [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) format (e.g. `2022-02-11T01:00:00Z`)
+* `formatBytesBin`: formats an amount of bytes using powers of 1024 (e.g. `7055258` bytes will be `6.7 MiB`) 
+* `formatBytesDec`: formats an amount of bytes using powers of 1000 (e.g. `7055258` bytes will be `7.1 MB`)
+* `env`: returns the value of the environment variable of the given key if set
+
+## Special characters in notification URLs
+
+The value given to `NOTIFICATION_URLS` is a comma separated list of URLs.
+If such a URL contains special characters (e.g. commas) these need to be URL encoded.
+To obtain an encoded version of your URL, you can use the CLI tool provided by `shoutrrr` (which is the library used for sending notifications):
+
+```
+docker run --rm -ti containrrr/shoutrrr generate [service]
+```
+
+where service is any of the [supported services][shoutrrr-docs], e.g. for SMTP:
+
+```
+docker run --rm -ti containrrr/shoutrrr generate smtp
+```

docs/how-tos/stop-containers-during-backup.md

@@ -0,0 +1,35 @@
+---
+title: Stop containers during backup
+layout: default
+parent: How Tos
+nav_order: 1
+---
+
+# Stop containers during backup
+
+In many cases, it will be desirable to stop the services that are consuming the volume you want to backup in order to ensure data integrity.
+This image can automatically stop and restart containers and services.
+By default, any container that is labeled `docker-volume-backup.stop-during-backup=true` will be stopped before the backup is being taken and restarted once it has finished.
+
+In case you need more fine grained control about which containers should be stopped (e.g. when backing up multiple volumes on different schedules), you can set the `BACKUP_STOP_CONTAINER_LABEL` environment variable and then use the same value for labeling:
+
+```yml
+version: '3'
+
+services:
+  app:
+    # definition for app ...
+    labels:
+      - docker-volume-backup.stop-during-backup=service1
+
+  backup:
+    image: offen/docker-volume-backup:v2
+    environment:
+      BACKUP_STOP_CONTAINER_LABEL: service1
+    volumes:
+      - data:/backup/my-app-backup:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+volumes:
+  data:
+```

docs/how-tos/update-deprecated-email-config.md

@@ -0,0 +1,26 @@
+---
+title: Update deprecated email configuration
+layout: default
+parent: How Tos
+nav_order: 18
+---
+
+# Update deprecated email configuration
+
+Starting with version 2.6.0, configuring email notifications using `EMAIL_*` keys has been deprecated.
+Instead of providing multiple values using multiple keys, you can now provide a single URL for `NOTIFICATION_URLS`.
+
+Before:
+```ini
+EMAIL_NOTIFICATION_RECIPIENT="you@example.com"
+EMAIL_NOTIFICATION_SENDER="no-reply@example.com"
+EMAIL_SMTP_HOST="posteo.de"
+EMAIL_SMTP_PASSWORD="secret"
+EMAIL_SMTP_USERNAME="me"
+EMAIL_SMTP_PORT="587"
+```
+
+After:
+```ini
+NOTIFICATION_URLS=smtp://me:secret@posteo.de:587/?fromAddress=no-reply@example.com&toAddresses=you@example.com
+```

docs/how-tos/use-custom-docker-host.md

@@ -0,0 +1,17 @@
+---
+title: Use a custom Docker host
+layout: default
+parent: How Tos
+nav_order: 14
+---
+
+# Use a custom Docker host
+
+If you are interfacing with Docker via TCP, set `DOCKER_HOST` to the correct URL.
+
+```ini
+DOCKER_HOST=tcp://docker_socket_proxy:2375
+```
+
+In case you are using a socket proxy, it must support `GET` and `POST` requests to the `/containers` endpoint. If you are using Docker Swarm, it must also support the `/services` endpoint. If you are using pre/post backup commands, it must also support the `/exec` endpoint.
+

docs/how-tos/use-rootless-docker.md

@@ -0,0 +1,23 @@
+---
+title: Use with rootless Docker
+layout: default
+parent: How Tos
+nav_order: 15
+---
+
+# Use with rootless Docker
+
+It's also possible to use this image with a [rootless Docker installation][rootless-docker].
+Instead of mounting `/var/run/docker.sock`, mount the user-specific socket into the container:
+
+```yml
+services:
+  backup:
+    image: offen/docker-volume-backup:v2
+    # ... configuration omitted
+    volumes:
+      - backup:/backup:ro
+      - /run/user/1000/docker.sock:/var/run/docker.sock:ro
+```
+
+[rootless-docker]: https://docs.docker.com/engine/security/rootless/

docs/how-tos/use-with-docker-swarm.md

@@ -0,0 +1,27 @@
+---
+title: Use with Docker Swarm
+layout: default
+parent: How Tos
+nav_order: 13
+---
+
+# Use with Docker Swarm
+
+By default, Docker Swarm will restart stopped containers automatically, even when manually stopped.
+If you plan to have your containers / services stopped during backup, this means you need to apply the `on-failure` restart policy to your service's definitions.
+A restart policy of `always` is not compatible with this tool.
+
+---
+
+When running in Swarm mode, it's also advised to set a hard memory limit on your service (~25MB should be enough in most cases, but if you backup large files above half a gigabyte or similar, you might have to raise this in case the backup exits with `Killed`):
+
+```yml
+services:
+  backup:
+    image: offen/docker-volume-backup:v2
+    deployment:
+      resources:
+        limits:
+          memory: 25M
+```
+