Eduardo David Paredes Vara
127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
# Kopia backups to Cloudflare R2
|
|
|
|
This directory defines restore-focused backups for the Docker services that are actually running on the host. It uses Kopia with Cloudflare R2 as an S3-compatible repository.
|
|
|
|
## Policy
|
|
|
|
- Use Kopia as the only backup engine.
|
|
- Store the repository in Cloudflare R2.
|
|
- Keep secrets outside this repo in `/opt/kopia/kopia.env`.
|
|
- Snapshot data needed to restore services and configuration.
|
|
- Generate logical database dumps before each snapshot.
|
|
- Include Paperless documents and Gitea repositories.
|
|
- Exclude Nextcloud user data/multimedia until storage usage and R2 cost are explicitly accepted.
|
|
|
|
Current size check on 2026-04-27:
|
|
|
|
| Path | Size |
|
|
| --- | ---: |
|
|
| `/opt/paperless` | 316M |
|
|
| `/opt/gitea` | 6.0M |
|
|
| `/opt/nextcloud` | 2.8G |
|
|
| `/opt/onlyoffice` | 4.3M |
|
|
| `/opt/authentik` | 8.3M |
|
|
| `/opt/trilium` | 3.6M |
|
|
| `/opt/karakeep` | 5.2M |
|
|
| `/opt/spintools` | 335M |
|
|
|
|
## What is backed up
|
|
|
|
The snapshot paths are listed in `backup-paths.txt`. The important choices are:
|
|
|
|
- Paperless: `/opt/paperless/data`, `/opt/paperless/media`, export and consume directories.
|
|
- Gitea: `/opt/gitea/data` and runner data.
|
|
- Nextcloud: config, themes and a MariaDB dump only. `/opt/nextcloud/data`, `/opt/nextcloud/custom_apps` and `/opt/nextcloud/html` are excluded.
|
|
- Databases: PostgreSQL and MariaDB dumps are written to `/opt/kopia/staging/dumps/latest`.
|
|
- Service configuration: deployment repo, Traefik, Authentik, n8n, Memos, Vikunja, Trilium, Karakeep, AdGuard, WireGuard, mail relay, Beszel, Homepage, Dozzle, Kasm and OpenCode.
|
|
- Local active deployments: Scheduler, Spintools, THSCOM, OpenClaw restore state and OpenCode runtime state.
|
|
|
|
Live database directories are excluded when a logical dump exists. Kasm's PostgreSQL database is backed up with `pg_dump`; Docker image/layer storage under `/opt/kasm/opt/docker` is intentionally excluded because it is rebuildable and large. OpenProject's embedded PostgreSQL data is not dumped by this first version; treat its restore as best-effort unless a service-specific dump command is added.
|
|
|
|
## Install Kopia
|
|
|
|
Install Kopia on the host using the package method appropriate for the server. Then create the runtime directory:
|
|
|
|
```bash
|
|
sudo mkdir -p /opt/kopia
|
|
sudo cp backups/kopia/env.example /opt/kopia/kopia.env
|
|
sudo chmod 600 /opt/kopia/kopia.env
|
|
```
|
|
|
|
Edit `/opt/kopia/kopia.env` and set the R2 bucket, endpoint, access keys and `KOPIA_PASSWORD`.
|
|
|
|
Cloudflare R2 endpoint format:
|
|
|
|
```text
|
|
<account_id>.r2.cloudflarestorage.com
|
|
```
|
|
|
|
## Initialize
|
|
|
|
```bash
|
|
backups/kopia/init-r2-repository.sh
|
|
```
|
|
|
|
## Run manually
|
|
|
|
```bash
|
|
backups/kopia/run-backup.sh
|
|
```
|
|
|
|
The script:
|
|
|
|
1. Creates database dumps.
|
|
2. Snapshots the paths in `backup-paths.txt`.
|
|
3. Applies retention: latest 7, daily 7, weekly 4, monthly 6.
|
|
4. Runs `kopia repository validate-provider`.
|
|
|
|
## Enable timer
|
|
|
|
Install the scripts under `/opt/kopia/scripts`; systemd should not execute them directly from a home directory on SELinux-enforcing hosts.
|
|
|
|
```bash
|
|
sudo install -d -m 0755 /opt/kopia/scripts
|
|
sudo install -m 0755 backups/kopia/*.sh /opt/kopia/scripts/
|
|
sudo install -m 0644 backups/kopia/backup-paths.txt backups/kopia/excludes.txt /opt/kopia/scripts/
|
|
sudo cp backups/kopia/systemd/kopia-docker-backup.* /etc/systemd/system/
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now kopia-docker-backup.timer
|
|
```
|
|
|
|
## Web UI
|
|
|
|
Kopia UI is exposed at:
|
|
|
|
```text
|
|
https://kopia.sherlockhomeless.net
|
|
```
|
|
|
|
The service listens only on the Docker host gateway `10.0.0.1:51515` and is published through Traefik using a local `traefik-kopia.yml` copied from `traefik-kopia.yml.example`.
|
|
|
|
Credentials are stored outside the repo in `/opt/kopia/kopia.env`:
|
|
|
|
```bash
|
|
sudo awk -F= '/^KOPIA_SERVER_USERNAME|^KOPIA_SERVER_PASSWORD/ {print}' /opt/kopia/kopia.env
|
|
```
|
|
|
|
Install or update the service and Traefik route:
|
|
|
|
```bash
|
|
sudo cp backups/kopia/systemd/kopia-server.service /etc/systemd/system/
|
|
cp backups/kopia/traefik-kopia.yml.example backups/kopia/traefik-kopia.yml
|
|
# Edit backups/kopia/traefik-kopia.yml and replace the Basic auth placeholder.
|
|
sudo cp backups/kopia/traefik-kopia.yml /opt/traefik/dynamic/kopia.yml
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now kopia-server.service
|
|
```
|
|
|
|
## Restore smoke test
|
|
|
|
Requires `jq`.
|
|
|
|
```bash
|
|
backups/kopia/restore-smoke-test.sh /tmp/kopia-restore-test
|
|
```
|
|
|
|
For real restores, restore into a temporary directory first, stop the target service, move data into place with correct ownership, then start the stack and validate the application.
|