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.
┌───────────── 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.
INCLUDE_PROJECT_NAME
Define this environment variable if your backup destination paths needs project name as a prefix. This is useful when running multiple projects.
EXCLUDE_BIND_MOUNTS
Docker has to volumes types. Binds and volumes.
Volumes are docker volumes (docker`volume list
).
Binds are paths mapped into the container from
the host for example in the volumes
section
of a service.
If defined all host binds will be ignored globally. This is useful when you only care about actual docker volumes. Often host binds are only used for mapping in configuration. This saves the user from manually excluding these bind volumes.
SWARM_MODE
If defined containers in swarm stacks are also evaluated.
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.
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:
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:
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.
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.
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/<service_name>/all_databases.sql
.
Example:
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.
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/<service_name>/all_databases.sql
.
Example:
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.
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/<service_name>/<POSTGRES_DB>.sql
.
Warning
Currently only the POSTGRES_DB
database
is dumped.
Example:
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: