add clickhouse backup guide

guides/backup-restore-clickhouse.md

@@ -0,0 +1,135 @@
+Guide to backing up and restoring `plausible_events_db`. Based on ["Backup and Restore" from ClickHouse.](https://clickhouse.com/docs/en/operations/backup/)
+
+**Note:** following this guide you'd need to stop some containers and it would make your plausible instance temporarily unavailable.
+
+---
+
+### Plan
+
+1. dump contents of the Plausible tables (events, sessions, imported\_\*) to files in a mounted volume
+1. load dumps from the mounted volume into `plausible_events_db`
+
+---
+
+### Backup
+
+1. Add backup config to allow reading backup files in the ClickHouse container
+
+```console
+$ touch clickhouse/backups.xml
+```
+
+```xml
+<clickhouse>
+    <storage_configuration>
+        <disks>
+            <backups>
+                <type>local</type>
+                <path>/backups/</path>
+            </backups>
+        </disks>
+    </storage_configuration>
+    <backups>
+        <allowed_disk>backups</allowed_disk>
+        <allowed_path>/backups/</allowed_path>
+    </backups>
+</clickhouse>
+```
+
+2. Add backups volume to `plausible_events_db` in your `docker-compose.yml`
+
+```diff
+  plausible_events_db:
+    image: clickhouse/clickhouse-server:22.6
+    volumes:
+      - event-data:/var/lib/clickhouse
+      - ./clickhouse/:/etc/clickhouse-server/config.d/
++     - ./clickhouse-backups:/backups
+```
+
+3. Stop relevant containers to avoid writing to old `plausible_events_db`
+
+```console
+> docker compose stop plausible plausible_events_db
+[+] Running 2/2
+ ⠿ Container hosting-plausible-1            Stopped           6.5s
+ ⠿ Container hosting-plausible_events_db-1  Stopped           0.2s
+```
+
+4. Restart `plausible_events_db` container to attach volume
+
+```console
+> docker compose up plausible_events_db -d
+[+] Running 1/1
+ ⠿ Container hosting-plausible_events_db-1  Started           0.3s
+```
+
+5. Dump old `plausible_events_db` contents to backup files
+
+```console
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.events TO Disk('backups', 'events.zip')'"
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.sessions TO Disk('backups', 'sessions.zip')'"
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.imported_visitors TO Disk('backups', 'imported_visitors.zip')'"
+
+# etc.
+```
+
+**TODO:** script
+
+6. (Optional) verify backup went OK
+
+```console
+> ls backups
+events.zip  sessions.zip  imported_visitors.zip ...
+```
+
+7. Move the backups somewhere, like a different host
+
+### Restore
+
+1. Ensure relevant containers are stopped
+
+```console
+> docker compose stop plausible plausible_events_db
+[+] Running 2/2
+ ⠿ Container hosting-plausible-1            Stopped           0.0s
+ ⠿ Container hosting-plausible_events_db-1  Stopped           0.2s
+```
+
+3. Ensure backup config from step 1 and backups mount from step 2 are still present.
+
+4. Load data into from backups. **TODO:** User + permissions
+
+```console
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.events FROM Disk('backups', 'events.zip')'"
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.sessions FROM Disk('backups', 'sessions.zip')'"
+> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.imported_visitors FROM Disk('backups', 'imported_visitors.zip')'"
+
+# etc.
+```
+
+6. Start all other containers
+
+```console
+> docker compose up -d
+[+] Running 4/4
+ ⠿ Container hosting-plausible_events_db-1  Running           0.0s
+ ⠿ Container hosting-mail-1                 Running           0.0s
+ ⠿ Container hosting-plausible_db-1         Started           0.5s
+ ⠿ Container hosting-plausible-1            Started           0.5s
+```
+
+7. (Optional) Remove backups from `docker-compose.yml` and your filesystem
+
+```diff
+  plausible_events_db:
+    image: clickhouse/clickhouse-server:22.6
+    volumes:
+      - event-data:/var/lib/clickhouse
+      - ./clickhouse/:/etc/clickhouse-server/config.d/
+-     - ./clickhouse-backups:/backups
+```
+
+```
+> rm -rf ./clickhouse-backups
+```

guides/backup-restore-postgres.md

@@ -0,0 +1 @@
+Please see [upgrading `plausible_db` (PostgreSQL)](upgrade/postgres.md) for backup/restore steps.