docs: document automatic Postgres upgrades via pgautoupgrade

Replace the hand-rolled entrypoint.postgres.sh.tmpl (which apt-installed
the old PG binaries and ran initdb + pg_upgrade --link by hand) with the
pgautoupgrade/pgautoupgrade:18-alpine image, matching the other recipes.
PGDATA is pinned to the legacy /var/lib/postgresql/data so the existing
cluster on the volume is upgraded in place rather than re-initialised.
Drops the db_entrypoint config and DB_ENTRYPOINT_VERSION.

.drone.yml

@@ -45,7 +45,7 @@ steps:
         from_secret: drone_abra-bot_token
       fork: true
       repositories:
-        - coop-cloud/auto-recipes-catalogue-json
+        - toolshed/auto-recipes-catalogue-json
 
 trigger:
   event: tag

.env.sample

@@ -6,9 +6,6 @@ DOMAIN=plausible.example.com
 #EXTRA_DOMAINS=', `www.plausible.example.com`'
 LETS_ENCRYPT_ENV=production
 
-ADMIN_USER_EMAIL=replace-me
-ADMIN_USER_NAME=replace-me
-ADMIN_USER_PWD=replace-me
 SECRET_KEY_BASE=replace-me
 DISABLE_AUTH=replace-me # true or false
 DISABLE_REGISTRATION=replace-me # true or false

README.md

@@ -7,7 +7,7 @@
 * **Status**: 1, alpha
 * **Image**: [`plausible/analytics`](https://hub.docker.com/plausible/analytics), 4, upstream
 * **Healthcheck**:
-* **Backups**: No
+* **Backups**: Yes
 * **Email**: No
 * **Tests**:
 * **SSO**: No
@@ -24,6 +24,14 @@
 5. `abra app deploy YOURAPPDOMAIN`
 6. Open the configured domain in your browser to finish set-up
 
+## Postgres upgrades
+
+The `db` service uses the
+[`pgautoupgrade`](https://github.com/pgautoupgrade/pgautoupgrade) image, so when
+the recipe bumps the Postgres major version the existing cluster is upgraded in
+place automatically on the next `deploy` — no manual migration steps. As with
+any major database upgrade, **take a backup of the `<stack_name>_db` volume
+first** (e.g. `abra app backup <domain>`).
+
 [`abra`]: https://git.coopcloud.tech/coop-cloud/abra
 [`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik
-p-cloud/traefik

abra.sh

@@ -1,2 +1,3 @@
-export CLICKHOUSE_CONF_VERSION=v1
+export CLICKHOUSE_CONF_VERSION=v2
 export CLICKHOUSE_USER_CONF_VERSION=v2
+export CLICKHOUSE_ENTRYPOINT_VERSION=v3

compose.yml

@@ -3,20 +3,22 @@ version: "3.8"
 
 services:
   app:
-    image: plausible/analytics:v1.5.1
+    image: plausible/analytics:v2.0.0
-    command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh db init-admin && /entrypoint.sh run"
+    command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:
       - db
       - events_db
     environment:
       - BASE_URL=https://$DOMAIN
-      - ADMIN_USER_EMAIL
-      - ADMIN_USER_NAME
-      - ADMIN_USER_PWD
       - SECRET_KEY_BASE
       - DATABASE_URL=postgres://plausible:plausible@${STACK_NAME}_db:5432/plausible
+      - CLICKHOUSE_DATABASE_URL=http://${STACK_NAME}_plausible_events_db:8123/plausible_events_db
       - SMTP_HOST_ADDR
       - MAILER_EMAIL
+      - SMTP_HOST_PORT
+      - SMTP_USER_NAME
+      - SMTP_USER_PWD
+      - SMTP_HOST_SSL_ENABLED
       - DISABLE_REGISTRATION
       - DISABLE_AUTH
     networks:
@@ -31,29 +33,56 @@ services:
         - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})"
         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-        - coop-cloud.${STACK_NAME}.version=1.1.0+1.5.1
+        - coop-cloud.${STACK_NAME}.version=4.0.0+v2.0.0
   db:
-    image: postgres:13.11-alpine
+    image: pgautoupgrade/pgautoupgrade:18-alpine
     volumes:
       - db-data:/var/lib/postgresql/data
     environment:
+      # pin legacy PGDATA so the existing cluster on the volume is upgraded in place, not re-init'd
+      - PGDATA=/var/lib/postgresql/data
       - POSTGRES_USER=plausible
       - POSTGRES_PASSWORD=plausible
       - POSTGRES_DB=plausible
     networks:
       - internal
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U plausible -d plausible"]
+      interval: 5s
+      timeout: 5s
+      retries: 60
+    deploy:
+      labels:
+        backupbot.backup: "true"
+        backupbot.backup.pre-hook: sh -c 'pg_dump -U "$$POSTGRES_USER" -Fc "$$POSTGRES_DB" | gzip > "/postgres.dump.gz"'
+        backupbot.backup.path: "/postgres.dump.gz"
+        backupbot.backup.post-hook: "rm -f /postgres.dump.gz"
+        backupbot.restore: "true"
+        backupbot.restore.post-hook: sh -c 'gzip -d /postgres.dump.gz && pg_restore --clean -U "$$POSTGRES_USER" --dbname="$$PLAUSIBLE_DB" < /postgres.dump && rm -f /postgres.dump'
 
   plausible_events_db:
     image: clickhouse/clickhouse-server:23.4.2.11-alpine
     volumes:
       - event-data:/var/lib/clickhouse
+    entrypoint: /custom-entrypoint.sh
     configs:
       - source: clickhouse-config
         target: /etc/clickhouse-server/config.d/logging.xml
       - source: clickhouse-user-config
         target: /etc/clickhouse-server/users.d/clickhouse-user-config.xml
+      - source: clickhouse_entrypoint
+        target: /custom-entrypoint.sh
+        mode: 0555
     networks:
       - internal
+    deploy:
+      labels:
+        backupbot.backup: "true"
+        backupbot.backup.pre-hook: clickhouse-backup create events
+        backupbot.backup.path: "/var/lib/clickhouse/backup/events"
+        backupbot.backup.post-hook: "rm -rf /var/lib/clickhouse/backup/events"
+        backupbot.restore: "true"
+        backupbot.restore.post-hook: clickhouse-backup restore --rm events && rm -rf /var/lib/clickhouse/backup/events"
 
 volumes:
   db-data:
@@ -71,3 +100,6 @@ configs:
   clickhouse-user-config:
     name: ${STACK_NAME}_clickhouse_user_config_${CLICKHOUSE_USER_CONF_VERSION}
     file: clickhouse-user-config.xml
+  clickhouse_entrypoint:
+    name: ${STACK_NAME}_clickhouse_entrypoint_${CLICKHOUSE_ENTRYPOINT_VERSION}
+    file: entrypoint.clickhouse.sh

entrypoint.clickhouse.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# clickhouse entrypoint (cc-ci Q4.7b hardening — recipe-PR for recipe-maintainers/plausible).
+#
+# clickhouse-backup is the BACKUP tool (backupbot pre/post-hooks: `clickhouse-backup create/restore`).
+# It is NOT required for clickhouse-SERVER (`/entrypoint.sh`) to run. The published recipe fetched it
+# with `set -ex` + a single silenced no-retry wget to ephemeral /tmp, so ANY transient failure of the
+# 22 MB GitHub download (rate-limit / network) exited the container BEFORE the server started → swarm
+# restarted it → re-downloaded → amplified the throttle → crash-loop → deploy timeout (cc-ci Q4.7).
+#
+# Hardening (no behaviour change when the download succeeds first try):
+#   - cache the binary on the PERSISTENT clickhouse data volume (/var/lib/clickhouse) so it is fetched
+#     at most once and reused on every container restart (no re-download amplification);
+#   - retry with backoff to ride out transient GitHub failures;
+#   - un-silenced so a failure is diagnosable in `docker service logs`.
+#
+# Policy: clickhouse-backup is REQUIRED. If it cannot be installed after all retries the entrypoint
+# aborts (non-zero exit) and the server is NOT started — we deliberately fail the deploy loudly rather
+# than come up silently without backup/restore capability.
+
+set -e
+
+CLICKHOUSE_BACKUP_VERSION=2.4.2
+
+ARCH=$(uname -m)
+if [[ $ARCH =~ "aarch64" ]]; then
+  ARCH="arm64"
+elif [[ $ARCH =~ "armv5l" ]]; then
+  ARCH="armv5"
+elif [[ $ARCH =~ "armv6l" ]]; then
+  ARCH="armv6"
+elif [[ $ARCH =~ "armv7l" ]]; then
+  ARCH="armv7"
+elif [[ $ARCH =~ "x86_64" ]]; then
+  ARCH="amd64"
+fi
+
+CACHE_DIR=/var/lib/clickhouse/.ccci-bin
+CACHED="${CACHE_DIR}/clickhouse-backup"
+BIN=/usr/local/bin/clickhouse-backup
+URL="https://github.com/AlexAkulov/clickhouse-backup/releases/download/v${CLICKHOUSE_BACKUP_VERSION}/clickhouse-backup-linux-${ARCH}.tar.gz"
+
+install_clickhouse_backup() {
+  mkdir -p "$CACHE_DIR"
+  if [ -x "$CACHED" ]; then
+    cp -f "$CACHED" "$BIN"
+    echo "clickhouse-backup: restored from persistent cache ($CACHED)"
+    return 0
+  fi
+  for attempt in 1 2 3 4 5; do
+    if wget --continue --output-document=/tmp/clickhouse-backup.tar.gz "$URL" \
+       && tar -xf /tmp/clickhouse-backup.tar.gz --directory=/usr/local/bin --strip-components=3; then
+      cp -f "$BIN" "$CACHED" 2>/dev/null || true
+      echo "clickhouse-backup: downloaded + cached (attempt ${attempt})"
+      return 0
+    fi
+    echo "clickhouse-backup: fetch attempt ${attempt} failed; backing off $((attempt * 10))s" >&2
+    sleep $((attempt * 10))
+  done
+  echo "clickhouse-backup: fetch FAILED after all retries — aborting; clickhouse-server will NOT start (backup tool is required)" >&2
+  return 1
+}
+
+# Required: if the backup tool cannot be installed after retries, abort (set -e) so the deploy fails
+# loudly instead of coming up without backup/restore capability.
+install_clickhouse_backup
+
+exec /entrypoint.sh

release/2.0.0+v1.5.1

@@ -0,0 +1,7 @@
+If you're upgrading from a pre-release version, there will be a major Postgresql
+version upgrade -- this should happen automatically, but **please take a
+backup**, at least of the `<stack_name>_db` volume, if not all the data volumes,
+before the upgrade. 
+
+If you haven't taken a backup already, it's probably safest to bail using
+Ctrl+C, take the backup, and re-run your `upgrade` / `deploy` command.

release/3.0.0+v2.0.0

@@ -0,0 +1,8 @@
+⚠ WARNING! ⚠
+
+This major version upgrade of Plausible requires running a manual data migration
+-- otherwise you'll see all historical data disappear (don't worry, it's
+"probably" still there). 
+
+Take a manual docker volume backup, then see here, and strap in: 
+https://github.com/plausible/analytics/discussions/3132