First doc version
This commit is contained in:
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!
|
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::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 3
|
||||||
:caption: Contents:
|
:caption: Contents:
|
||||||
|
|
||||||
|
guide/install
|
||||||
|
guide/configuration
|
||||||
|
guide/advanced
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
@ -19,3 +22,5 @@ Indices and tables
|
||||||
* :ref:`genindex`
|
* :ref:`genindex`
|
||||||
* :ref:`modindex`
|
* :ref:`modindex`
|
||||||
* :ref:`search`
|
* :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):
|
def forget(repository: str, daily: str, weekly: str, monthly: str, yearly: str):
|
||||||
return commands.run(restic(repository, [
|
return commands.run(restic(repository, [
|
||||||
'forget',
|
'forget',
|
||||||
|
'--group-by',
|
||||||
|
'paths',
|
||||||
'--keep-daily',
|
'--keep-daily',
|
||||||
daily,
|
daily,
|
||||||
'--keep-weekly',
|
'--keep-weekly',
|
||||||
|
|
Loading…
Reference in New Issue