From fb3c564d7a618882d9913440f6d69e51e5ec81bd Mon Sep 17 00:00:00 2001 From: Einar Forselv Date: Mon, 9 Dec 2019 03:57:16 +0100 Subject: [PATCH] First doc version --- docs/guide/advanced.rst | 26 ++++ docs/guide/configuration.rst | 223 ++++++++++++++++++++++++++++ docs/guide/install.rst | 53 +++++++ docs/index.rst | 9 +- src/restic_compose_backup/restic.py | 2 + 5 files changed, 311 insertions(+), 2 deletions(-) create mode 100644 docs/guide/advanced.rst create mode 100644 docs/guide/configuration.rst create mode 100644 docs/guide/install.rst diff --git a/docs/guide/advanced.rst b/docs/guide/advanced.rst new file mode 100644 index 0000000..5d5ff38 --- /dev/null +++ b/docs/guide/advanced.rst @@ -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//` + in the backup process container. `/volumes` is pushed into restic +* Databases are backed up from stdin / dumps into restic using path + `/databases//dump.sql` +* Cron triggers backup at 2AM every day diff --git a/docs/guide/configuration.rst b/docs/guide/configuration.rst new file mode 100644 index 0000000..cf72c40 --- /dev/null +++ b/docs/guide/configuration.rst @@ -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//dump.sql` or similar. diff --git a/docs/guide/install.rst b/docs/guide/install.rst new file mode 100644 index 0000000..8802d38 --- /dev/null +++ b/docs/guide/install.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 5273e56..31cd612 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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/ diff --git a/src/restic_compose_backup/restic.py b/src/restic_compose_backup/restic.py index 2bf2a60..5f79f90 100644 --- a/src/restic_compose_backup/restic.py +++ b/src/restic_compose_backup/restic.py @@ -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',