diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index 35d6482f4..cc9ee5b4b 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -47,3 +47,157 @@ You can then recreate the database container and restore the backup using the `` If you have set different options for the database container before, e.g. setting it in a specific network and giving it a fixed IP, you should also set these options here. For more information on backing up a PostgreSQL database and restoring a backup, see the `PostgreSQL documentation on Backup and Restore `_ + +Differential Backup Using Borgmatic +----------------------------------- + +In case of large databases, the additional space required for more than one backup can be prohibitive. Differential backups instead only save changes since the last full backup. + +`Borg `_ is a well-established tool for performing differential backups. `Borgmatic `_ provides it in a docker container and adds some utility. Both are free and open source software. + +For this configuration we suggest the use of docker compose. Change to the directory containing your compose file and create the directories required for borgmatic: + +.. code-block:: bash + + mkdir -p data/{borgmatic.d,repository,.config,.ssh,.cache} + +Add the borgmatic container as backup service into the `compose file `_ from the sampledb repository: + +.. code-block:: yaml + + services: + backup: + image: ghcr.io/borgmatic-collective/borgmatic:2.0.12 + container_name: backup + restart: always + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./data/repository:/mnt/borg-repository + # This binds to the config file directory. Set repo and postgres password (same as in db) there. + - ./data/borgmatic.d:/etc/borgmatic.d/ + - ./data/.config/borg:/root/.config/borg + - ./data/.ssh:/root/.ssh + - ./data/.cache/borg:/root/.cache/borg + - ./data/.state/borgmatic:/root/.local/state/borgmatic + environment: + - TZ=Europe/Berlin + - DOCKERCLI=true + - BACKUP_CRON=00 03 * * * + networks: + - sampledb-net + ... + +In ``./data/borgmatic.d`` create ``config.yaml``. This configuration file should look like this: + +.. code-block:: yaml + + source_directories: [] + + repositories: + - path: /mnt/borg-repository/repo + one_file_system: true + read_special: true + + # Set a proper passphrase for production + encryption_passphrase: "DoNotForgetToChangeYourPassphrase" + compression: lz4 + archive_name_format: 'backup-{now}' + + keep_daily: 7 + keep_weekly: 4 + keep_monthly: 12 + keep_yearly: 10 + + checks: + - name: repository + frequency: 2 weeks + - name: archives + frequency: always + - name: extract + frequency: 2 weeks + - name: data + frequency: 1 month + + postgresql_databases: + - name: all + hostname: db + port: 5432 + # Remember to set username and password to the same values as in the compose file. + # If no username is set there, it is the default "postgres". + username: postgres + password: password + + commands: + - before: repository + when: + - prune + - create + - compact + run: + - echo "`date` - Starting backup create/prune/compact." + - docker stop sampledb + + - after: repository + when: + - create + - prune + - compact + run: + - docker start sampledb + + - after: error + run: + - echo "Error during borgmatic action." + - docker start sampledb + + # Example apprise configuration for email alerts - set url as you require + apprise: + services: + - url: mailtos://sender:password@example.com?to=recipient@example.com + label: example-email + fail: + title: SampleDB Backup Failed + body: Borgmatic encountered an error. + states: + - fail + +Start all involved containers and use this command to initialize the repository: + +.. code-block:: bash + + docker exec -it backup borgmatic --verbosity 1 init --encryption repokey + +Secure the repository keys, by exporting them and backing them up at a secure location: + +.. code-block:: bash + + docker exec -it backup borg key export --paper /mnt/borg-repository/repo > encrypted-key-backup.txt + +Do a manual backup to see if everything works as intended: + +.. code-block:: bash + + docker exec -it backup borgmatic --stats --verbosity 1 + +To restore, first clear the database container and associated data, just as above: + +.. code-block:: bash + + docker compose down db + docker volume rm docker_pgdata + rm -rf /opt/docker/sampledb/volumes/pgdata + +Then recreate the directory and database container: + +.. code-block:: bash + + mkdir /opt/docker/sampledb/volumes/pgdata/ + docker compose up -d db + +And, finally, restore the latest archive of the database using borgmatic: + +.. code-block:: bash + + docker exec -it backup borgmatic --verbosity 1 extract --config /etc/borgmatic.d/wiki_config.yaml --archive latest + +Find further information on borgmatic and its database backup and restore in its `documentation `_. diff --git a/docs/changelog.rst b/docs/changelog.rst index 943cf7640..ff6ac24f4 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -19,6 +19,7 @@ Currently in development. - Split setting for showing topics in navbar for actions and instruments tabs - Added webhook type for changes to object permissions - Fixed array tables +- Added documentation for differential backups using borgmatic Version 0.32