Configuration ============= Environment Variables --------------------- RESTIC_REPOSITORY ~~~~~~~~~~~~~~~~~ Sets the restic repository path. This is a standard environment variable the ``restic`` command will read making it simple for us to enter the container and use the restic command directly. More about this value and supported backends: https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html RESTIC_PASSWORD ~~~~~~~~~~~~~~~ Sets the password is used to encrypt/decrypt data. Losing this password will make recovery impossible. This is a standard environment variable the ``restic`` command will read making it simple for us to enter the container running the command directly. RESTIC_KEEP_DAILY ~~~~~~~~~~~~~~~~~ **Default value**: ``7`` How many daily snapshots (grouped by path) back in time we want to keep. This is passed to restic in the ``forget --keep-daily`` option. RESTIC_KEEP_WEEKLY ~~~~~~~~~~~~~~~~~~ **Default value**: ``4`` How many weeks back we should keep at least one snapshot (grouped by path). This is passed to restic in the ``forget --keep-weekly`` option. RESTIC_KEEP_MONTHLY ~~~~~~~~~~~~~~~~~~~ **Default value**: ``12`` How many months back we should keep at least on snapshot (grouped by path). This is passed to restic in the ``forget --keep-monthly`` option. The schedule parameters only accepts numeric values and is validated when the container starts. Providing values cron does not understand will stall all backup. RESTIC_KEEP_YEARLY ~~~~~~~~~~~~~~~~~~ **Default value**: ``3`` How many years back we should keep at least one snapshot (grouped by path). This is passed to restic in the ``forget --keep-yearly`` option. CRON_SCHEDULE ~~~~~~~~~~~~~ **Default value**: ``0 2 * * *`` (daily at 02:00) The cron schedule parameters. The crontab is generated when the container starts from the ``CRON_SCHEDULE`` and ``CRON_COMMAND`` env variables. .. code:: ┌───────────── minute (0 - 59) │ ┌───────────── hour (0 - 23) │ │ ┌───────────── day of the month (1 - 31) │ │ │ ┌───────────── month (1 - 12) │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ * * * * * command to execute CRON_COMMAND ~~~~~~~~~~~~ **Default value**: ``source /env.sh && rcb backup > /proc/1/fd/1`` The command executed in the crontab. A single line is generated when the container starts from the ``CRON_SCHEDULE`` and ``CRON_COMMAND`` environment variables. The default command sources a dump of all env vars, runs the backup command and directs output to pid 1 so it appears in docker logs. By default the crontab will look like this:: 0 2 * * * source /env.sh && rcb backup > /proc/1/fd/1 LOG_LEVEL ~~~~~~~~~ **Default value**: ``info`` Log level for the ``rcb`` command. Valid values are ``debug``, ``info``, ``warning``, ``error``. EMAIL_HOST ~~~~~~~~~~ The email host to use. Alerts can be tested using the ``rcb alerts`` command. This will send a test message to all configured alert backends. EMAIL_PORT ~~~~~~~~~~ The port to connect to Alerts can be tested using the ``rcb alerts`` command. This will send a test message to all configured alert backends. EMAIL_HOST_USER ~~~~~~~~~~~~~~~ The user of the sender account Alerts can be tested using the ``rcb alerts`` command. This will send a test message to all configured alert backends. EMAIL_HOST_PASSWORD ~~~~~~~~~~~~~~~~~~~ The password for the sender account Alerts can be tested using the ``rcb alerts`` command. This will send a test message to all configured alert backends. EMAIL_SEND_TO ~~~~~~~~~~~~~ The email address to send alerts Alerts can be tested using the ``rcb alerts`` command. This will send a test message to all configured alert backends. DISCORD_WEBHOOK ~~~~~~~~~~~~~~~ The discord webhook url. And administrator can quickly set this up by going to server settings in the discord client and create a webhook that will post embedded messages to a specific channel. The url usually looks like this: ``https://discordapp.com/api/webhooks/...``` DOCKER_HOST ~~~~~~~~~~~ **Default value**: ``unix://tmp/docker.sock`` The socket or host of the docker service. DOCKER_TLS_VERIFY ~~~~~~~~~~~~~~~~~ If defined verify the host against a CA certificate. Path to certs is defined in ``DOCKER_CERT_PATH`` and can be copied or mapped into this backup container. DOCKER_CERT_PATH ~~~~~~~~~~~~~~~~ A path to a directory containing TLS certificates to use when connecting to the Docker host. Combined with ``DOCKER_TLS_VERIFY`` this can be used to talk to docker through TLS in cases were we cannot map in the docker socket. Compose Labels -------------- What is backed up is controlled by simple labels in the compose yaml file. At any point we can verify this configuration by running the ``rcb status`` command. .. code: $ docker-compose run --rm backup rcb status INFO: Status for compose project 'myproject' INFO: Repository: '' INFO: Backup currently running?: False INFO: --------------- Detected Config --------------- INFO: service: mysql INFO: - mysql (is_ready=True) INFO: service: mariadb INFO: - mariadb (is_ready=True) INFO: service: postgres INFO: - postgres (is_ready=True) INFO: service: web INFO: - volume: media INFO: - volume: /srv/files Here we can see what volumes and databases are detected for backup. Volumes ~~~~~~~ To enable volume backup for a service we simply add the `restic-compose-backup.volumes: true` label. The value must be ``true``. Example: .. code:: yaml myservice: image: some_image labels: restic-compose-backup.volumes: true volumes: - uploaded_media:/srv/media - uploaded_files:/srv/files - /srv/data:/srv/data volumes: media: files: This will back up the three volumes mounted to this service. Their path in restic will be: - /volumes/myservice/srv/media - /volumes/myservice/srv/files - /volumes/myservice/srv/data A simple `include` and `exclude` filter for what volumes should be backed up is also available. Note that this includes or excludes entire volumes and are not include/exclude patterns for files in the volumes. .. note:: The ``exclude`` and ``include`` filtering is applied on the source path, not the destination. Include example including two volumes only: .. code:: yaml myservice: image: some_image labels: restic-compose-backup.volumes: true restic-compose-backup.volumes.include: "uploaded_media,uploaded_files" volumes: - uploaded_media:/srv/media - uploaded_files:/srv/files - /srv/data:/srv/data volumes: media: files: Exclude example achieving the same result as the example above. .. code:: yaml example: image: some_image labels: restic-compose-backup.volumes: true restic-compose-backup.volumes.exclude: "data" volumes: # Excluded by filter - media:/srv/media # Backed up - files:/srv/files - /srv/data:/srv/data volumes: media: files: The ``exclude`` and ``include`` tag can be used together in more complex situations. mariadb ~~~~~~~ To enable backup of mariadb simply add the ``restic-compose-backup.mariadb: true`` label. Credentials are fetched from the following environment variables in the mariadb service. This is the standard when using the official mariadb_ image. .. code:: MYSQL_USER MYSQL_PASSWORD Backups are done by dumping all databases directly into restic through stdin using ``mysqldump``. It will appear in restic as a separate snapshot with path ``/databases//all_databases.sql``. .. warning: This will only back up the databases the ``MYSQL_USER` has access to. If you have multiple databases this must be taken into consideration. Example: .. code:: yaml mariadb: image: mariadb:10 labels: restic-compose-backup.mariadb: true env_file: mariadb-credentials.env volumes: - mariadb:/var/lib/mysql volumes: mariadb: mysql ~~~~~ To enable backup of mysql simply add the ``restic-compose-backup.mysql: true`` label. Credentials are fetched from the following environment variables in the mysql service. This is the standard when using the official mysql_ image. .. code:: MYSQL_USER MYSQL_PASSWORD Backups are done by dumping all databases directly into restic through stdin using ``mysqldump``. It will appear in restic as a separate snapshot with path ``/databases//all_databases.sql``. .. warning: This will only back up the databases the ``MYSQL_USER` has access to. If you have multiple databases this must be taken into consideration. Example: .. code:: yaml mysql: image: mysql:5 labels: restic-compose-backup.mysql: true env_file: mysql-credentials.env volumes: - mysql:/var/lib/mysql volumes: mysql: postgres ~~~~~~~~ To enable backup of mysql simply add the ``restic-compose-backup.postgres: true`` label. Credentials are fetched from the following environment variables in the postgres service. This is the standard when using the official postgres_ image. .. code:: POSTGRES_USER POSTGRES_PASSWORD POSTGRES_DB Backups are done by dumping the ``POSTGRES_DB`` directly into restic through stdin using ``pg_dump``. It will appear in restic as a separate snapshot with path ``/databases//.sql``. .. warning:: Currently only the ``POSTGRES_DB`` database is dumped. Example: .. code:: yaml postgres: image: postgres:11 labels: # Enables backup of this database restic-compose-backup.postgres: true env_file: postgres-credentials.env volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata: .. _mariadb: https://hub.docker.com/_/mariadb .. _mysql: https://hub.docker.com/_/mysql .. _postgres: https://hub.docker.com/_/postgres