### Install Dependencies and Serve Documentation

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/README.md

Run these commands to install necessary Ruby gems and start a local Jekyll server for the documentation site. Changes to configuration files may require a server restart.

```bash
bundle install
bundle exec jekyll serve
```

--------------------------------

### Docker Compose Setup for Recurring Backups

Source: https://github.com/offen/docker-volume-backup/blob/main/README.md

Integrate this service into your Docker Compose setup to automate recurring backups. Ensure volumes are mounted correctly and consider the `docker-volume-backup.stop-during-backup` label for data integrity. Lock image tags to specific release versions in production.

```yaml
services:
  volume-consumer:
    build:
      context: ./my-app
    volumes:
      - data:/var/my-app
    labels:
      # This means the container will be stopped during backup to ensure
      # backup integrity. You can omit this label if stopping during backup
      # not required.
      - docker-volume-backup.stop-during-backup=true

  backup:
    # In production, it is advised to lock your image tag to a proper
    # release version instead of using `latest`.
    # Check https://github.com/offen/docker-volume-backup/releases
    # for a list of available releases.
    image: offen/docker-volume-backup:latest
    restart: always
    env_file: ./backup.env # see below for configuration reference
    volumes:
      - data:/backup/my-app-backup:ro
      # Mounting the Docker socket allows the script to stop and restart
      # the container during backup. You can omit this if you don't want
      # to stop the container. In case you need to proxy the socket, you can
      # also provide a location by setting `DOCKER_HOST` in the container
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # If you mount a local directory or volume to `/archive` a local
      # copy of the backup will be stored there. You can override the
      # location inside of the container by setting `BACKUP_ARCHIVE`.
      # You can omit this if you do not want to keep local backups.
      - /path/to/local_backups:/archive
volumes:
  data:
```

--------------------------------

### Configure Backup Pruning with Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/automatically-prune-old-backups.md

Use this Docker Compose configuration to set backup retention policies. `BACKUP_RETENTION_DAYS` defines how old backups can be, and `BACKUP_PRUNING_PREFIX` limits deletions to files starting with a specific prefix.

```yaml
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:
```

--------------------------------

### Execute manual backup with specific configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/manual-trigger.md

When multiple backup schedules are configured, source the specific environment configuration file before executing the `backup` command. This ensures the correct schedule is used. Replace `<container_ref>` and `myconf.env` with your specific values.

```console
docker exec <container_ref> /bin/sh -c 'set -a; source /etc/dockervolumebackup/conf.d/myconf.env; set +a && backup'
```

--------------------------------

### Execute basic manual backup

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/manual-trigger.md

Run the `backup` command directly inside the container to trigger a manual backup. Replace `<container_ref>` with your container's reference.

```console
docker exec <container_ref> backup
```

--------------------------------

### Run All Integration Tests

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

Execute the entire test suite for docker-volume-backup. This is the main entry point for testing.

```sh
./test.sh
```

--------------------------------

### Docker CLI for One-Off Backups

Source: https://github.com/offen/docker-volume-backup/blob/main/README.md

Execute a single backup operation using the Docker CLI. Mount the target volume and provide necessary environment variables for authentication and destination. The `--entrypoint backup` flag ensures the backup command is executed.

```bash
docker run --rm \
  -v data:/backup/data \
  --env AWS_ACCESS_KEY_ID="<xxx>" \
  --env AWS_SECRET_ACCESS_KEY="<xxx>" \
  --env AWS_S3_BUCKET_NAME="<xxx>" \
  --entrypoint backup \
  offen/docker-volume-backup:v2
```

--------------------------------

### Pre-backup Database Dump with mysqldump

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/run-custom-commands.md

Use the `archive-pre` label to run `mysqldump` before the tar archive is created. Commands requiring redirection must be executed via `/bin/sh -c`.

```yaml
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:
```

--------------------------------

### Print Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/print-configuration.md

Execute this command to display the configuration that docker-volume-backup has loaded. Errors during configuration sourcing are printed to stdout for debugging.

```bash
docker exec <container_ref> backup print-config
```

--------------------------------

### Backup Jitter Delay

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Configures an optional startup delay (jitter) before each backup run. Set to "0s" or omit to disable. The value should be a Go time.Duration string.

```shell
# BACKUP_JITTER="0s"
```

--------------------------------

### Database Dump with mariadb-dump/mysqldump

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Prepare database backups using `mariadb-dump` or `mysqldump` before the main backup process. Use the `docker-volume-backup.archive-pre` label on the database service to specify the pre-backup command.

```yaml
services:
  database:
    image: mariadb:latest
    labels:
      - docker-volume-backup.archive-pre=/bin/sh -c 'mariadb-dump -psecret --all-databases > /tmp/dumps/dump.sql'
    volumes:
      - data:/tmp/dumps
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      BACKUP_FILENAME: db.tar.gz
      BACKUP_CRON_EXPRESSION: "0 2 * * *"
    volumes:
      - ./local:/archive
      - data:/backup/data:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Print Configuration with Specific Values

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/print-configuration.md

Test a one-off configuration value by passing it directly as an environment variable. This is useful for debugging specific settings. Note that secrets are included in the output.

```bash
docker exec -e BACKUP_SOURCES=/backup -e NOTIFICATION_URLS=stdout:// <container_ref> backup print-config
```

--------------------------------

### Build Docker Image for Tests

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

Build an up-to-date docker-volume-backup image from the current source tree before running tests. Set BUILD_IMAGE=1 to enable this behavior.

```sh
BUILD_IMAGE=1 ./test.sh
```

--------------------------------

### Backup to Dropbox using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Set up a Docker service for backing up volumes to Dropbox. Obtain and configure Dropbox API keys and refresh token as environment variables.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      DROPBOX_REFRESH_TOKEN: REFRESH_KEY  # replace
      DROPBOX_APP_KEY: APP_KEY  # replace
      DROPBOX_APP_SECRET: APP_SECRET  # replace
      DROPBOX_REMOTE_PATH: /somedir  # replace
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Test Case Prelude with Utilities

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

A common prelude for test case scripts that sets the current directory, sources utility functions from util.sh, and determines the current test name.

```sh
cd "$(dirname "$0")"
. ../util.sh
current_test=$(basename $(pwd))
```

--------------------------------

### Backup to SSH using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Set up a Docker service to back up volumes over SSH. Configure SSH host, port, user, and remote path. Ensure the private key is mounted.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      SSH_HOST_NAME: server.local
      SSH_PORT: 2222
      SSH_USER: user
      SSH_REMOTE_PATH: /data
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /path/to/private_key:/root/.ssh/id_rsa

volumes:
  data:
```

--------------------------------

### Pulling Docker Image from Docker Hub and GitHub Container Registry

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/index.md

Demonstrates how to pull the Docker image from both Docker Hub and the GitHub Container Registry. It is recommended to use specific version tags (e.g., ':v2') instead of 'latest' in production environments.

```bash
docker pull offen/docker-volume-backup:v2
```

```bash
docker pull ghcr.io/offen/docker-volume-backup:v2
```

--------------------------------

### Multiple Backup Instances

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Run multiple instances of the backup service for different data volumes. Use YAML anchors and aliases for configuration reuse and specify unique labels for `BACKUP_STOP_DURING_BACKUP_LABEL` to manage container stops.

```yaml
services:
  # ... define other services using the `data_1` and `data_2` volumes here
  backup_1:
    image: offen/docker-volume-backup:v2
    environment:
      BACKUP_CRON_EXPRESSION: "0 2 * * *"
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      # Label the container using the `data_1` volume as `docker-volume-backup.stop-during-backup=service1`
      BACKUP_STOP_DURING_BACKUP_LABEL: service1
    volumes:
      - data_1:/backup/data-1-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
  backup_2:
    <<: *backup_service
    environment:
      <<: *backup_environment
      # Label the container using the `data_2` volume as `docker-volume-backup.stop-during-backup=service2`
      BACKUP_STOP_DURING_BACKUP_LABEL: service2
    volumes:
      - data_2:/backup/data-2-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data_1:
  data_2:
```

--------------------------------

### Backup to MinIO using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure a Docker service for backing up volumes to a MinIO instance. Specify the MinIO endpoint and access credentials.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_ENDPOINT: minio.example.com
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: MINIOACCESSKEY
      AWS_SECRET_ACCESS_KEY: MINIOSECRETKEY
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Backup to WebDAV using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure a Docker service to back up volumes to a WebDAV server. Provide the WebDAV URL, path, username, and password.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      WEBDAV_URL: https://webdav.mydomain.me
      WEBDAV_PATH: /my/directory/
      WEBDAV_USERNAME: user
      WEBDAV_PASSWORD: password
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Backup Compression Algorithm

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Specifies the compression algorithm for backups. Valid options are "gz" (Gzip), "zst" (Zstd), or "none" (tar only). Defaults to "gz".

```shell
# BACKUP_COMPRESSION="gz"
```

--------------------------------

### Run Docker Volume Backup as Non-Root User

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-as-non-root.md

Execute the backup tool as a non-root user by specifying the user and group ID (e.g., 1000:1000) with the `--user` flag. This is useful for environments where running as root is restricted.

```bash
docker run --rm \
  -v data:/backup/data \
  --env AWS_ACCESS_KEY_ID="<xxx>" \
  --env AWS_SECRET_ACCESS_KEY="<xxx>" \
  --env AWS_S3_BUCKET_NAME="<xxx>" \
  --entrypoint backup \
  --user 1000:1000 \
  offen/docker-volume-backup:v2
```

--------------------------------

### Run as Non-Root User

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure the backup container to run as a non-root user by specifying the `user` directive in the service definition. Ensure the user ID and group ID (e.g., 1000:1000) have the necessary permissions for volume access.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    user: 1000:1000
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    volumes:
      - data:/backup/my-app-backup:ro

volumes:
  data:
```

--------------------------------

### Backup to Filebase using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Set up a Docker service to back up volumes to Filebase, a S3-compatible object storage. Configure the S3 endpoint and Filebase credentials.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_ENDPOINT: s3.filebase.com
      AWS_S3_BUCKET_NAME: filebase-bucket
      AWS_ACCESS_KEY_ID: FILEBASE-ACCESS-KEY
      AWS_SECRET_ACCESS_KEY: FILEBASE-SECRET-KEY
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Running Pre-backup Commands as a Specific User

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/run-custom-commands.md

Specify a custom user for pre- or post-backup commands using the `docker-volume-backup.[step]-[pre|post].user` label. Ensure the specified user exists within the target container's environment.

```yaml
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'
```

--------------------------------

### Backup Locally using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure a Docker service to back up volumes to local storage. Define the backup filename format and a symlink for the latest backup.

```yaml
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_LATEST_SYMLINK: backup-latest.tar.gz
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ${HOME}/backups:/archive

volumes:
  data:
```

--------------------------------

### Replace exec-pre and exec-post labels

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/replace-deprecated-exec-labels.md

Update your labels to use `archive-pre` and `archive-post` instead of the deprecated `exec-pre` and `exec-post` to run commands before and after archiving.

```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
```

--------------------------------

### Specify Backup Sources per Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/run-multiple-schedules.md

Control which volume mounts are backed up by setting the `BACKUP_SOURCES` environment variable within each configuration file. This allows for distinct backup targets when using multiple schedules.

```ini
# In the 1st config file:
BACKUP_SOURCES=/backup/app1_data
```

```ini
# In the 2nd config file:
BACKUP_SOURCES=/backup/app2_data
```

--------------------------------

### Scale Service to Zero for Backup

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-with-docker-swarm.md

Label services in the 'deploy' section to automatically scale them down to zero replicas before backup and scale them back up afterward. This method is suitable for services deployed in replicated mode.

```yaml
services:
  app:
    image: myorg/myimage:latest
    deploy:
      labels:
        - docker-volume-backup.stop-during-backup=true
      replicas: 2
```

--------------------------------

### Configure Docker Credentials for Tests

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

Use host credentials for tests, especially in CI environments, by setting DOCKER_CONFIG_FILE to the path of your config.json file. Otherwise, an empty config is used.

```sh
DOCKER_CONFIG_FILE=${HOME}/.docker/config.json ./test.sh
```

--------------------------------

### Docker Compose for Backup with Archive Hooks

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/replace-deprecated-backup-from-snapshot.md

Use this Docker Compose configuration to implement backup strategies with pre and post-archive hooks. It defines services for the application and the backup utility, along with volumes for data and intermediate backup storage.

```yaml
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:
```

--------------------------------

### Custom Commands with EXEC_LABEL for Specific Backup Instances

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/run-custom-commands.md

When using multiple backup instances or schedules, specify `docker-volume-backup.exec-label` on containers with custom commands and set the `EXEC_LABEL` environment variable in the backup container to ensure commands run only for the intended instance.

```yaml
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:
```

--------------------------------

### Docker Compose configuration for rsync uploads

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/handle-file-uploads-using-third-party-tools.md

Configure your Docker Compose file to use a custom image and define a `docker-volume-backup.copy-post` label. This label specifies the command to execute rsync for uploading the backup archive.

```yaml
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:ro

  # other services defined here ...
volumes:
  app_data:
```

--------------------------------

### Run Single Integration Test Case

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

Execute a specific test case by providing its directory name as an argument to the test script. This allows for focused testing.

```sh
./test.sh <directory-name>
```

--------------------------------

### Docker Compose for Multiple Schedules

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/run-multiple-schedules.md

Define a Docker Compose service to run the backup container. Mounts are configured to allow multiple configuration files and access to Docker socket and backup volumes.

```yaml
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:
```

--------------------------------

### List Docker Volumes

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/restore-volumes-from-backup.md

Command to list all Docker volumes, useful for identifying the exact name of a volume when using docker-compose.

```console
docker volume ls
```

--------------------------------

### Backup to Azure Blob Storage using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure a Docker service to back up volumes to Azure Blob Storage. Provide container name, account name, and the primary account key.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AZURE_STORAGE_CONTAINER_NAME: backup-container
      AZURE_STORAGE_ACCOUNT_NAME: account-name
      AZURE_STORAGE_PRIMARY_ACCOUNT_KEY: Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Restore Volume via Temporary Container

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/restore-volumes-from-backup.md

This process involves using a temporary container to copy backup data into a mounted volume. Ensure the volume name and backup path are correct.

```console
docker run -d --name temp_restore_container -v data:/backup_restore alpine
```

```console
docker cp /tmp/backup/data-backup temp_restore_container:/backup_restore
```

```console
docker stop temp_restore_container
```

```console
docker rm temp_restore_container
```

--------------------------------

### Recurring Backups with Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/index.md

Configure a 'backup' service in your docker-compose.yml to handle recurring backups. Ensure to lock image tags to specific release versions in production. Mounting the Docker socket is optional but allows for container stopping/restarting during backup and access to labels for custom commands. Mounting a local directory to `/archive` stores local copies of backups.

```yaml
services:
  volume-consumer:
    build:
      context: ./my-app
    volumes:
      - data:/var/my-app
    labels:
      # This means the container will be stopped during backup to ensure
      # backup integrity. You can omit this label if stopping during backup
      # not required.
      - docker-volume-backup.stop-during-backup=true

  backup:
    # In production, it is advised to lock your image tag to a proper
    # release version instead of using `latest`.
    # Check https://github.com/offen/docker-volume-backup/releases
    # for a list of available releases.
    image: offen/docker-volume-backup:latest
    restart: always
    env_file: ./backup.env # see below for configuration reference
    volumes:
      - data:/backup/my-app-backup:ro
      # Mounting the Docker socket allows the script to stop and restart
      # the container during backup and to access the container labels to
      # specify custom commands. You can omit this if you don't want to
      # stop the container or run custom commands. In case you need to
      # proxy the socket, you can also provide a location by setting
      # `DOCKER_HOST` in the container
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # If you mount a local directory or volume to `/archive` a local
      # copy of the backup will be stored there. You can override the
      # location inside of the container by setting `BACKUP_ARCHIVE`.
      # You can omit this if you do not want to keep local backups.
      - /path/to/local_backups:/archive
volumes:
  data:
```

--------------------------------

### Enable Filename Expansion

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

When set to `true`, allows environment variable placeholders in `BACKUP_FILENAME`, `BACKUP_LATEST_SYMLINK`, and `BACKUP_PRUNING_PREFIX` to be expanded at runtime. Expansion occurs before strftime token interpolation. Note that `$` must be escaped (e.g., `$$VAR`) in docker-compose.yml.

```shell
# BACKUP_FILENAME_EXPAND="true"
```

--------------------------------

### Run Tests Against Specific Docker Image Tag

Source: https://github.com/offen/docker-volume-backup/blob/main/test/README.md

Compare behavior by running tests against a different existing docker-volume-backup image. Specify the desired image tag using IMAGE_TAG.

```sh
IMAGE_TAG=v2.30.0 ./test.sh
```

--------------------------------

### Backup to AWS S3

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure backups to be stored in an AWS S3 bucket. Ensure AWS credentials and bucket name are set in the environment variables.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ${HOME}/backups:/archive

volumes:
  data:
```

--------------------------------

### Asymmetric GPG Encryption

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Encrypt backups asymmetrically using GPG with a public key. Provide the public key in the `GPG_PUBLIC_KEY_RING` environment variable.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      GPG_PUBLIC_KEY_RING: |
        -----BEGIN PGP PUBLIC KEY BLOCK-----

        D/cIHu6GH/0ghlcUVSbgMg5RRI5QKNNKh04uLAPxr75mKwUg0xPUaWgyyrAChVBi
        ...
        -----END PGP PUBLIC KEY BLOCK-----
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Backup to MinIO using Docker Secrets

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Securely back up volumes to MinIO by using Docker secrets for access keys. The keys are mounted from Docker secrets into the container.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_ENDPOINT: minio.example.com
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID_FILE: /run/secrets/minio_access_key
      AWS_SECRET_ACCESS_KEY_FILE: /run/secrets/minio_secret_key
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    secrets:
      - minio_access_key
      - minio_secret_key

volumes:
  data:

secrets:
  minio_access_key:
    # ... define how secret is accessed
  minio_secret_key:
    # ... define how secret is accessed
```

--------------------------------

### Daily Backup Retention Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/define-different-retention-schedules.md

Configure daily backups to be retained for 7 days. Ensure the cron expression runs daily at 2 AM and the pruning prefix matches the daily backup filename.

```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"
```

--------------------------------

### Migrate BACKUP_STOP_CONTAINER_LABEL to BACKUP_STOP_DURING_BACKUP_LABEL

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/replace-deprecated-backup-stop-container-label.md

Update your environment variable configuration to use the new setting name. This change is a direct key rename.

```diff
    env:
-     BACKUP_STOP_CONTAINER_LABEL: database
+     BACKUP_STOP_DURING_BACKUP_LABEL: database
```

--------------------------------

### Configure Docker Compose for Non-Root User

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-as-non-root.md

Configure your Docker Compose file to run the backup service as a non-root user by setting the `user` attribute to the desired user and group ID (e.g., 1000:1000).

```yaml
services:
  backup:
    image: offen/docker-volume-backup:v2
    user: 1000:1000
    # further configuration omitted ...
```

--------------------------------

### Stop Containers Directly for Backup

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-with-docker-swarm.md

Label containers directly to stop them before backup and restart them afterward. This approach requires the 'on-failure' restart policy and bypasses service definitions.

```yaml
services:
  app:
    image: myapp/myimage:latest
    labels:
      - docker-volume-backup.stop-during-backup=true
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
```

--------------------------------

### Monthly Backup Retention Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/define-different-retention-schedules.md

Configure monthly backups to be retained indefinitely. The cron expression should run on the first day of every month at 4 AM, and the pruning prefix must match the monthly backup filename.

```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 * *"
```

--------------------------------

### Custom Dockerfile for rsync integration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/handle-file-uploads-using-third-party-tools.md

Use this Dockerfile to build a custom image that includes rsync, extending the base Docker volume backup image. This allows you to use rsync for file uploads.

```Dockerfile
FROM offen/docker-volume-backup:v2

RUN apk add rsync
```

--------------------------------

### Rollback Volume to Snapshot

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/restore-volumes-from-backup.md

This command creates a new volume and restores it from a full backup archive. It mounts the target volume, a read-only archive directory, and then extracts the backup. Ensure the archive filename and path are correct.

```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
```

--------------------------------

### Deprecated: Bind-Mount Time Zone Files

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-container-timezone.md

This method is deprecated. It involves bind-mounting time zone files from the host system into the container. If `TZ` is set, it takes precedence.

```yaml
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
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro

volumes:
  data:
```

--------------------------------

### Stop and Restart Containers with Labels

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/stop-containers-during-backup.md

Use the `docker-volume-backup.stop-during-backup` label to automatically stop containers before a backup and restart them afterward. This is useful for ensuring data integrity when backing up volumes.

```yaml
services:
  app:
    # definition for app ...
    labels:
      - docker-volume-backup.stop-during-backup=service1

  backup:
    image: offen/docker-volume-backup:v2
    environment:
      BACKUP_STOP_DURING_BACKUP_LABEL: service1
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Updated Email Configuration with NOTIFICATION_URLS

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/update-deprecated-email-config.md

This snippet demonstrates the new format for email notification configuration using a single `NOTIFICATION_URLS` value.

```ini
NOTIFICATION_URLS=smtp://me:secret@posteo.de:587/?fromAddress=no-reply@example.com&toAddresses=you@example.com
```

--------------------------------

### Customize Notification Templates

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-up-notifications.md

Mount custom Go template files into the container at /etc/dockervolumebackup/notifications.d/ to override default notification titles and bodies. Ensure nested templates are defined to override specific values.

```yaml
services:
  backup:
    image: offen/docker-volume-backup:v2
    volumes:
      - ./customized.template:/etc/dockervolumebackup/notifications.d/01.template
```

```go-template
{{ define "title_success" -}}
✅ Successfully ran backup {{ .Config.BackupStopDuringBackupLabel }}
{{- 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 }}
```

--------------------------------

### Weekly Backup Retention Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/define-different-retention-schedules.md

Configure weekly backups to be retained for 31 days. The cron expression should run every Monday at 3 AM, and the pruning prefix must match the weekly backup filename.

```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"
```

--------------------------------

### Untar Backup Archive

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/restore-volumes-from-backup.md

Use this command to extract the contents of a backup archive to a specified directory.

```console
tar -C /tmp -xvf  backup.tar.gz
```

--------------------------------

### Backup to AWS S3 using Docker Compose

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure a Docker service to back up volumes to an AWS S3 bucket. Ensure AWS credentials and bucket name are set in the environment variables.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Latest Backup Symlink

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Creates a symbolic link to the latest backup file when a value is provided. This setting only affects local backups.

```shell
# BACKUP_LATEST_SYMLINK=""
```

--------------------------------

### Custom Cron Schedule for Backups

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Set a custom cron schedule for when backups should run. The `BACKUP_CRON_EXPRESSION` variable accepts standard cron syntax.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      # take a backup on every hour
      BACKUP_CRON_EXPRESSION: "0 * * * *"
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Send Email Notifications on Failed Backups

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-up-notifications.md

Provide SMTP credentials, sender, and recipient addresses to enable email notifications for failed backup runs. Set NOTIFICATION_LEVEL to 'info' for success notifications.

```yaml
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
```

--------------------------------

### Backup Filename Format

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Defines the naming convention for backup files, supporting strftime format verbs. Omitting verbs will overwrite previous backups. The extension can be literal or templated via `{{ .Extension }}`.

```shell
# BACKUP_FILENAME="backup-%Y-%m-%dT%H-%M-%S.{{ .Extension }}"
```

--------------------------------

### Set Memory Limit for Backup Service

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-with-docker-swarm.md

Configure a hard memory limit for the docker-volume-backup service to prevent it from being killed during backup operations, especially when dealing with large files.

```yaml
services:
  backup:
    image: offen/docker-volume-backup:v2
    deployment:
      resources:
        limits:
          memory: 25M
```

--------------------------------

### Configure Rootless Docker Socket Mount

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/use-rootless-docker.md

Mount the user-specific Docker socket into the container when using rootless Docker. This replaces the default system-wide socket mount.

```yaml
services:
  backup:
    image: offen/docker-volume-backup:v2
    # ... configuration omitted
    volumes:
      - backup:/backup:ro
      - /run/user/1000/docker.sock:/var/run/docker.sock:ro

```

--------------------------------

### Decrypt GPG Encrypted Backup

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/encrypt-backups.md

Use this command to decrypt a backup file that was encrypted using GPG. Your operating system will prompt for the passphrase.

```bash
gpg -o backup.tar.gz -d backup.tar.gz.gpg
```

--------------------------------

### Rotate Backups Older Than 7 Days

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Configure automatic rotation of backups that are older than a specified number of days. Use `BACKUP_RETENTION_DAYS` to set the retention period and `BACKUP_PRUNING_PREFIX` to specify the prefix of backups to prune.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      BACKUP_FILENAME: backup-%Y-%m-%dT%H-%M-%S.tar.gz
      BACKUP_PRUNING_PREFIX: backup-
      BACKUP_RETENTION_DAYS: 7
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Symmetric GPG Encryption

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/recipes/index.md

Encrypt backups symmetrically using GPG with a provided passphrase. Set the `GPG_PASSPHRASE` environment variable for encryption.

```yaml
services:
  # ... define other services using the `data` volume here
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      AWS_S3_BUCKET_NAME: backup-bucket
      AWS_ACCESS_KEY_ID: AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      GPG_PASSPHRASE: somesecretstring
    volumes:
      - data:/backup/my-app-backup:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  data:
```

--------------------------------

### Backup Schedule Cron Expression

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Defines the schedule for backup runs using cron expressions. If not set, `@daily` (midnight) is used.

```shell
# BACKUP_CRON_EXPRESSION="@daily"
```

--------------------------------

### Deprecated Email Configuration

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/update-deprecated-email-config.md

This snippet shows the old way of configuring email notifications using multiple `EMAIL_*` keys.

```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"
```

--------------------------------

### Generate Dropbox OAuth2 Token

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-up-dropbox.md

Use this curl command to exchange an authorization code for access and refresh tokens. Replace placeholders with your actual APPKEY, APPSECRET, and AUTHCODE.

```bash
curl https://api.dropbox.com/oauth2/token \
    -d code=AUTHCODE \
    -d grant_type=authorization_code \
    -d client_id=APPKEY \
    -d client_secret=APPSECRET
```

--------------------------------

### Gzip Parallelism Level

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/reference/index.md

Sets the parallelism level for Gzip compression. Higher values can speed up compression. A value of 0 uses all available threads. Defaults to 1.

```shell
# GZIP_PARALLELISM="1"
```

--------------------------------

### Set Container Time Zone with TZ Environment Variable

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-container-timezone.md

Set the `TZ` environment variable to a valid tz database time zone to override the default UTC. This method is preferred for consistency and avoiding host dependencies.

```yaml
services:
  backup:
    image: offen/docker-volume-backup:v2
    environment:
      TZ: Europe/Berlin
    volumes:
      - data:/backup/my-app-backup:ro

volumes:
  data:
```

--------------------------------

### Generate Shoutrrr URL Encoder

Source: https://github.com/offen/docker-volume-backup/blob/main/docs/how-tos/set-up-notifications.md

Use this command to generate an encoded version of your notification URL, especially if it contains special characters like commas. Replace '[service]' with the desired notification service.

```bash
docker run --rm -ti ghcr.io/nicholas-fedor/shoutrrr generate [service]
```

```bash
docker run --rm -ti ghcr.io/nicholas-fedor/shoutrrr generate smtp
```