From 97809bda32ed2004669e17c59766090005c9e1c6 Mon Sep 17 00:00:00 2001 From: f-seidler Date: Mon, 2 Feb 2026 19:18:44 +0100 Subject: [PATCH 1/8] Update backup_and_restore.rst Added documentation for differential backup and restore using borgmatic. --- .../backup_and_restore.rst | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index 35d6482f4..898a7c56a 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -47,3 +47,166 @@ 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. Brogmatic provides it in a docker container and adds some utility. Both are free and open source software. + +For this configuration we recommend 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 to your compose file named for example ``compose.yaml`` (minimal working example): + +.. code-block:: yaml + + services: + backup: + image: ghcr.io/borgmatic-collective/borgmatic:2.0.12 + container_name: borgmatic + 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 sampledb-postgres) 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 * * * + + sampledb: + image: sciapp/sampledb:0.32.0 + container_name: sampledb + ports: + - 8000:8000 + environment: + - SAMPLEDB_CONTACT_EMAIL=admin@example.com + - SAMPLEDB_MAIL_SERVER=mail.example.com + - SAMPLEDB_MAIL_SENDER=sampledb@example.com + - SAMPLEDB_ADMIN_PASSWORD=password + # This varaible includes the postgres password, set it the same as in the sampledb-postgres service. + - SAMPLEDB_SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://postgres:password@sampledb-postgres:5432/postgres + restart: always + depends_on: + - sampledb-postgres + + sampledb-postgres: + image: postgres:15 + container_name: sampledb-postgres + environment: + - POSTGRES_PASSWORD=password + - PGDATA=/var/lib/postgresql/data/pgdata + volumes: + - pgdata:/var/lib/postgresql/data/pgdata:rw + restart: always + +In ``./data/borgmatic.d`` create ``config.yaml``. This conifguartion file should look like this: + +.. code-block:: yaml + + source_directories: [] + + repositories: + - path: /mnt/borg-repository/repo + one_file_system: true + read_special: true + + 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: sampledb-postgres + port: 5432 + username: postgres + password: password + + commands: + - before: repository + when: + - create + - prune + - compact + run: + - echo "`date` - Starting backup create/prune/compact." + - docker stop sampledb + + - after: repository + when: + - create + - prune + - compact + run: + - echo {containernames} | xargs docker start + - docker start sampledb + + - after: error + run: + - echo "Error during borgmatic action." + +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 sampledb-postgres + 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 sampledb-postgres + +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 `_. From 1796752af26b7b4cf1b861e540eaa59f7f63d34b Mon Sep 17 00:00:00 2001 From: f-seidler Date: Mon, 2 Feb 2026 19:42:03 +0100 Subject: [PATCH 2/8] Update changelog.rst V 0.33 added differential backup documentation --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) 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 From a364b9d8193af6eec3f08fa6ffdcf133b16a2d3e Mon Sep 17 00:00:00 2001 From: f-seidler Date: Wed, 4 Feb 2026 14:07:49 +0100 Subject: [PATCH 3/8] Update docs/administrator_guide/backup_and_restore.rst Adding the links is a great idea. Co-authored-by: Florian Rhiem --- docs/administrator_guide/backup_and_restore.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index 898a7c56a..ad68c87bc 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -53,7 +53,7 @@ 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. Brogmatic provides it in a docker container and adds some utility. Both are free and open source software. +`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 recommend the use of docker compose. Change to the directory containing your compose file and create the directories required for borgmatic: From df7514444aecce946ac37f1bb1d8e33522676a1e Mon Sep 17 00:00:00 2001 From: f-seidler Date: Wed, 4 Feb 2026 14:08:26 +0100 Subject: [PATCH 4/8] Update docs/administrator_guide/backup_and_restore.rst Agreed. Co-authored-by: Florian Rhiem --- docs/administrator_guide/backup_and_restore.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index ad68c87bc..fc26de2c6 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -55,7 +55,7 @@ In case of large databases, the additional space required for more than one back `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 recommend the use of docker compose. Change to the directory containing your compose file and create the directories required for borgmatic: +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 From e34e7f65a68d0fa8b057fc3dfa640527da0e6ab1 Mon Sep 17 00:00:00 2001 From: f-seidler Date: Wed, 4 Feb 2026 14:08:57 +0100 Subject: [PATCH 5/8] Update docs/administrator_guide/backup_and_restore.rst Sorry for the typo. Co-authored-by: Florian Rhiem --- docs/administrator_guide/backup_and_restore.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index fc26de2c6..7964d6235 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -94,7 +94,7 @@ Add the borgmatic container as backup service to your compose file named for exa - SAMPLEDB_MAIL_SERVER=mail.example.com - SAMPLEDB_MAIL_SENDER=sampledb@example.com - SAMPLEDB_ADMIN_PASSWORD=password - # This varaible includes the postgres password, set it the same as in the sampledb-postgres service. + # This variable includes the postgres password, set it the same as in the sampledb-postgres service. - SAMPLEDB_SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://postgres:password@sampledb-postgres:5432/postgres restart: always depends_on: From 9ec99cb289a6f5df8de555adb672c705a3f6b5d5 Mon Sep 17 00:00:00 2001 From: f-seidler Date: Wed, 4 Feb 2026 14:18:48 +0100 Subject: [PATCH 6/8] Update docs/administrator_guide/backup_and_restore.rst Co-authored-by: Florian Rhiem --- docs/administrator_guide/backup_and_restore.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index 7964d6235..bb6e9e254 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -110,7 +110,7 @@ Add the borgmatic container as backup service to your compose file named for exa - pgdata:/var/lib/postgresql/data/pgdata:rw restart: always -In ``./data/borgmatic.d`` create ``config.yaml``. This conifguartion file should look like this: +In ``./data/borgmatic.d`` create ``config.yaml``. This configuration file should look like this: .. code-block:: yaml From 40307a5ba2723c378921d7836311f5fcd0dcdc23 Mon Sep 17 00:00:00 2001 From: f-seidler Date: Wed, 4 Feb 2026 18:16:16 +0100 Subject: [PATCH 7/8] Update backup_and_restore.rst Reworked initial pull request accroding to the comments. --- .../backup_and_restore.rst | 136 ++++++++---------- 1 file changed, 63 insertions(+), 73 deletions(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index bb6e9e254..38ae84024 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -61,66 +61,44 @@ For this configuration we suggest the use of docker compose. Change to the direc mkdir -p data/{borgmatic.d,repository,.config,.ssh,.cache} -Add the borgmatic container as backup service to your compose file named for example ``compose.yaml`` (minimal working example): +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: borgmatic - 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 sampledb-postgres) 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 * * * - - sampledb: - image: sciapp/sampledb:0.32.0 - container_name: sampledb - ports: - - 8000:8000 - environment: - - SAMPLEDB_CONTACT_EMAIL=admin@example.com - - SAMPLEDB_MAIL_SERVER=mail.example.com - - SAMPLEDB_MAIL_SENDER=sampledb@example.com - - SAMPLEDB_ADMIN_PASSWORD=password - # This variable includes the postgres password, set it the same as in the sampledb-postgres service. - - SAMPLEDB_SQLALCHEMY_DATABASE_URI=postgresql+psycopg2://postgres:password@sampledb-postgres:5432/postgres - restart: always - depends_on: - - sampledb-postgres - - sampledb-postgres: - image: postgres:15 - container_name: sampledb-postgres - environment: - - POSTGRES_PASSWORD=password - - PGDATA=/var/lib/postgresql/data/pgdata - volumes: - - pgdata:/var/lib/postgresql/data/pgdata:rw - restart: always + image: ghcr.io/borgmatic-collective/borgmatic:2.0.12 + container_name: borgmatic + 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}' @@ -132,44 +110,56 @@ In ``./data/borgmatic.d`` create ``config.yaml``. This configuration file should checks: - name: repository - frequency: 2 weeks + frequency: 2 weeks - name: archives - frequency: always + frequency: always - name: extract - frequency: 2 weeks + frequency: 2 weeks - name: data - frequency: 1 month + frequency: 1 month postgresql_databases: - name: all - hostname: sampledb-postgres - port: 5432 - username: postgres - password: password - + hostname: db + port: 5432 + # Remember to set username and password to the same values as in the compose file + username: postgres + password: password + commands: - before: repository - when: - - create + when: - prune + - create - compact - run: + run: - echo "`date` - Starting backup create/prune/compact." - - docker stop sampledb - - - after: repository - when: - - create - - prune - - compact - run: - - echo {containernames} | xargs docker start - - docker start sampledb - - - after: error - run: - - echo "Error during borgmatic action." - + - 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 @@ -192,7 +182,7 @@ To restore, first clear the database container and associated data, just as abov .. code-block:: bash - docker compose down sampledb-postgres + docker compose down db docker volume rm docker_pgdata rm -rf /opt/docker/sampledb/volumes/pgdata @@ -201,7 +191,7 @@ Then recreate the directory and database container: .. code-block:: bash mkdir /opt/docker/sampledb/volumes/pgdata/ - docker compose up -d sampledb-postgres + docker compose up -d db And, finally, restore the latest archive of the database using borgmatic: From 6f8bea28bc6601ec205a5ed699d5c441225ce920 Mon Sep 17 00:00:00 2001 From: f-seidler Date: Mon, 9 Mar 2026 16:01:51 +0100 Subject: [PATCH 8/8] Update backup_and_restore.rst Corrected documentation in response to feedback. --- docs/administrator_guide/backup_and_restore.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/administrator_guide/backup_and_restore.rst b/docs/administrator_guide/backup_and_restore.rst index 38ae84024..cc9ee5b4b 100644 --- a/docs/administrator_guide/backup_and_restore.rst +++ b/docs/administrator_guide/backup_and_restore.rst @@ -68,7 +68,7 @@ Add the borgmatic container as backup service into the `compose file encrypted-key-backup.txt Do a manual backup to see if everything works as intended: