First doc version
This commit is contained in:
Einar Forselv
parent
151f3cfeeb
commit
fb3c564d7a
|
|
@ -0,0 +1,26 @@
|
|||
Advanced
|
||||
========
|
||||
|
||||
Temp Notes
|
||||
----------
|
||||
|
||||
* Quick setup guide from start to end
|
||||
* we group snapshots by path when forgetting
|
||||
* explain rcb commands
|
||||
* examples of using restic directly
|
||||
* Explain what happens during backup process
|
||||
* Explain the backup process container
|
||||
|
||||
Inner workings
|
||||
--------------
|
||||
|
||||
* Each service in the compose setup is configured with a label
|
||||
to enable backup of volumes or databases
|
||||
* When backup starts a new instance of the container is created
|
||||
mapping in all the needed volumes. It will copy networks etc
|
||||
to ensure databases can be reached
|
||||
* Volumes are mounted to `/volumes/<service_name>/<path>`
|
||||
in the backup process container. `/volumes` is pushed into restic
|
||||
* Databases are backed up from stdin / dumps into restic using path
|
||||
`/databases/<service_name>/dump.sql`
|
||||
* Cron triggers backup at 2AM every day
|
||||
|
|
@ -0,0 +1,223 @@
|
|||
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_BASE_URL
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
**Default value**: ``unix://tmp/docker.sock``
|
||||
|
||||
The location of the docker socket.
|
||||
|
||||
Compose Labels
|
||||
--------------
|
||||
|
||||
A simple `include` and `exclude` filter is also available.
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
example:
|
||||
image: some_image
|
||||
labels:
|
||||
restic-compose-backup.volumes: true
|
||||
restic-compose-backup.volumes.include: "files,data"
|
||||
volumes:
|
||||
# Source don't match include filter. No backup.
|
||||
- media:/srv/media
|
||||
# Matches include filter
|
||||
- files:/srv/files
|
||||
- /srv/data:/srv/data
|
||||
|
||||
volumes:
|
||||
media:
|
||||
files:
|
||||
|
||||
Exclude
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
example:
|
||||
image: some_image
|
||||
labels:
|
||||
restic-compose-backup.volumes: true
|
||||
restic-compose-backup.volumes.exclude: "media"
|
||||
volumes:
|
||||
# Excluded by filter
|
||||
- media:/srv/media
|
||||
# Backed up
|
||||
- files:/srv/files
|
||||
- /srv/data:/srv/data
|
||||
|
||||
volumes:
|
||||
media:
|
||||
files:
|
||||
|
||||
Databases
|
||||
|
||||
Will dump databases directly into restic through stdin.
|
||||
They will appear in restic as a separate snapshot with
|
||||
path `/databases/<service_name>/dump.sql` or similar.
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
restic-compose-backup is available at docker `docker hub`_.
|
||||
|
||||
.. code::
|
||||
|
||||
docker pull restic-compose-backup
|
||||
|
||||
Optionally it can be built from source using the github_ repository.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone https://github.com/ZettaIO/restic-compose-backup.git
|
||||
cd restic-compose-backup
|
||||
# Build and tag the image locally
|
||||
docker build src/ --tag restic-compose-backup
|
||||
|
||||
Bug reports and issues
|
||||
----------------------
|
||||
|
||||
Please report bugs an issues on github_
|
||||
|
||||
Development setup
|
||||
-----------------
|
||||
|
||||
Getting started with local development is fairly simple.
|
||||
The github_ repository contains a simple ``docker-compose.yaml``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
docker-compose up -d
|
||||
# Enter the container in sh
|
||||
docker-compose run --rm backup sh
|
||||
|
||||
The dev compose setup maps in the source from the host
|
||||
and the spawned backup container will inherit all
|
||||
the volumes from the backup service ensuring code changes
|
||||
propagates during development.
|
||||
|
||||
Set up a local venv and install the package in development mode::
|
||||
|
||||
python -m venv .venv
|
||||
. .venv/bin/activate
|
||||
pip install -e ./src
|
||||
|
||||
|
||||
.. _docker hub: https://hub.docker.com/r/zettaio/restic-compose-backup
|
||||
.. _github: https://github.com/ZettaIO/restic-compose-backup
|
||||
|
|
@ -6,12 +6,15 @@
|
|||
Welcome to restic-compose-backup's documentation!
|
||||
=================================================
|
||||
|
||||
Simple backup with restic for small to medium docker-compose setups.
|
||||
Simple backup with restic_ for docker-compose setups.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
:caption: Contents:
|
||||
|
||||
guide/install
|
||||
guide/configuration
|
||||
guide/advanced
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
@ -19,3 +22,5 @@ Indices and tables
|
|||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. _restic: https://restic.net/
|
||||
|
|
|
|||
|
|
@ -78,6 +78,8 @@ def is_initialized(repository: str) -> bool:
|
|||
def forget(repository: str, daily: str, weekly: str, monthly: str, yearly: str):
|
||||
return commands.run(restic(repository, [
|
||||
'forget',
|
||||
'--group-by',
|
||||
'paths',
|
||||
'--keep-daily',
|
||||
daily,
|
||||
'--keep-weekly',
|
||||
|
|
|
|||
Loading…
Reference in New Issue