[Repo] ci: Validate compose files; document updates and backups

.github/workflows/validate-compose.yml

@@ -0,0 +1,62 @@
+name: Validate Compose
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  structure:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check the 3-file convention
+        run: |
+          status=0
+          for dir in */; do
+            dir="${dir%/}"
+            files="$(ls -A "$dir" | LC_ALL=C sort | tr '\n' ' ')"
+            if [ "$files" != ".env.example README.md docker-compose.yml " ]; then
+              echo "::error file=$dir::$dir must contain exactly docker-compose.yml, .env.example and README.md (found: $files)"
+              status=1
+            fi
+          done
+          exit "$status"
+
+  compose-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Validate every docker-compose.yml
+        run: |
+          # Dokploy attaches dokploy-network on deploy, so declare it as an
+          # external network for validation only.
+          override="$RUNNER_TEMP/networks.override.yml"
+          printf 'networks:\n  dokploy-network:\n    external: true\n' > "$override"
+
+          status=0
+          for file in */docker-compose.yml; do
+            dir="$(dirname "$file")"
+            # Secrets left empty in .env.example on purpose would fail
+            # ${VAR:?msg}; give them a dummy value for validation only.
+            env_file="$RUNNER_TEMP/$dir.env"
+            sed -E 's/^([A-Za-z_][A-Za-z0-9_]*)=$/\1=ci-placeholder/' \
+              "$dir/.env.example" > "$env_file"
+            echo "::group::$file"
+            if docker compose -f "$file" -f "$override" \
+              --env-file "$env_file" config -q; then
+              echo "OK"
+            else
+              echo "::error file=$file::docker compose config failed"
+              status=1
+            fi
+            echo "::endgroup::"
+          done
+          exit "$status"

README.md

@@ -8,22 +8,25 @@ Docker Compose stacks, deployed via [Dokploy](https://dokploy.com).
 
 ## Services
 
-| Service | Description |
-| --- | --- |
-| [Apprise](apprise/) | Notification gateway |
-| [ArchiSteamFarm](archisteamfarm/) | Steam account management |
-| [Cloudflared](cloudflared/) | Cloudflare Tunnel |
-| [Garage](garage/) | S3-compatible storage for backups |
-| [Homepage](homepage/) | Dashboard and service portal |
-| [MySpotify](myspotify/) | Spotify listening statistics |
-| [n8n](n8n/) | Workflow automation |
-| [Pi-hole](pihole/) | DNS and ad blocking |
-| [Plex](plex/) | Media server |
-| [qBittorrent](qbittorrent/) | Torrent client |
-| [Speedtest](speedtest/) | Internet speed tracking |
-| [Traccar](traccar/) | GPS tracking server |
-| [Watchtower](watchtower/) | Automatic container updates |
-| [WGDashboard](wgdashboard/) | WireGuard VPN server and dashboard |
+| Service                           | Description                        | Backup                               |
+|-----------------------------------|------------------------------------|--------------------------------------|
+| [Apprise](apprise/)               | Notification gateway               | Daily (config volume)                |
+| [ArchiSteamFarm](archisteamfarm/) | Steam account management           | Daily (config and plugins volumes)   |
+| [Cloudflared](cloudflared/)       | Cloudflare Tunnel                  | Not needed (stateless)               |
+| [Garage](garage/)                 | S3-compatible storage for backups  | No (it is the backup target)         |
+| [Homepage](homepage/)             | Dashboard and service portal       | Daily (config volume)                |
+| [MySpotify](myspotify/)           | Spotify listening statistics       | Daily (MongoDB dump)                 |
+| [n8n](n8n/)                       | Workflow automation                | Daily (data volume)                  |
+| [Pi-hole](pihole/)                | DNS and ad blocking                | No (by choice)                       |
+| [Plex](plex/)                     | Media server                       | Weekly (config volume)               |
+| [qBittorrent](qbittorrent/)       | Torrent client                     | Daily (config volume)                |
+| [Speedtest](speedtest/)           | Internet speed tracking            | Daily (config volume)                |
+| [Traccar](traccar/)               | GPS tracking server                | Daily (database, managed separately) |
+| [Watchtower](watchtower/)         | Automatic container updates        | Not needed (stateless)               |
+| [WGDashboard](wgdashboard/)       | WireGuard VPN server and dashboard | Daily (data and config volumes)      |
+
+Backups are Dokploy backups to S3-compatible storage, configured outside
+this repository.
 
 ## Prerequisites
 

apprise/README.md

@@ -41,3 +41,9 @@ The API and the admin UI have no authentication of their own. Keep the
 service off the internet and, if the local network is not trusted, put
 an authentication layer in front of it (for example a reverse proxy
 with basic auth).
+
+## Updates
+
+Watchtower updates the `apprise` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `apprise/**`
+change on `main`.

archisteamfarm/README.md

@@ -38,3 +38,9 @@ With Docker Compose the real names are prefixed with the project name
 
 Connects to `cloudflare-exposed`
 (must be created by the `cloudflared` service first).
+
+## Updates
+
+Watchtower updates the `archisteamfarm` container automatically,
+following the `latest` tag. Dokploy redeploys the stack when files under
+`archisteamfarm/**` change on `main`.

cloudflared/README.md

@@ -55,3 +55,10 @@ networks:
 [tunnel-docs]: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/
 [zero-trust]: https://one.dash.cloudflare.com/
 [cloudflared-repo]: https://github.com/cloudflare/cloudflared
+
+## Updates
+
+Watchtower updates the `cloudflare-tunnel` container automatically,
+following the `latest` tag. Dokploy redeploys the stack when files under
+`cloudflared/**` change on `main`. While the tunnel restarts, every
+service exposed through it is briefly unreachable.

garage/README.md

@@ -58,4 +58,5 @@ docker exec garage /garage bucket allow --read --write backups --key backups-key
 Garage publishes only exact version tags (no `latest` or `v2`), so
 Watchtower cannot update it. Dependabot opens a pull request for each
 new 2.x release instead; major versions need a manual migration and are
-ignored.
+ignored. Dokploy redeploys the stack when files under `garage/**`
+change on `main`, so merging a Dependabot bump rolls it out.

homepage/README.md

@@ -64,3 +64,9 @@ with the named volume:
 
 Connects to `cloudflare-exposed`
 (must be created by the `cloudflared` service first).
+
+## Updates
+
+Watchtower updates the `homepage` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `homepage/**`
+change on `main`.

myspotify/README.md

@@ -68,3 +68,12 @@ Moving to `mongo:7` is not a simple retag: 7.0 cannot open 8.x
 data files, and `mongodump`/`mongorestore` only supports
 restoring into the same major version or FCV. Export the data
 with `mongoexport`/`mongoimport` instead.
+
+## Updates
+
+Watchtower updates all three containers automatically: the backend and
+frontend follow `latest`, and `myspotify-mongo` follows `8`, so it stays
+within MongoDB 8. A new MongoDB major is a manual change to the image tag
+and needs a dump and restore (see the kernel workaround notes above).
+Dokploy redeploys the stack when files under `myspotify/**` change on
+`main`.

n8n/README.md

@@ -49,3 +49,9 @@ name (for example `<project>_n8n-data`).
   n8n off the internet.
 - Nodes that read or write files are limited to `/tmp/github-bundles`
   (`N8N_RESTRICT_FILE_ACCESS_TO`), outside the data volume.
+
+## Updates
+
+Watchtower updates the `n8n` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `n8n/**`
+change on `main`.

pihole/README.md

@@ -30,3 +30,9 @@ nebula-sync).
 
 Connects to `cloudflare-exposed`
 (must be created by the `cloudflared` service first).
+
+## Updates
+
+Watchtower updates the `pihole` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `pihole/**`
+change on `main`.

plex/README.md

@@ -34,3 +34,9 @@ the backup so its databases stay consistent.
   The linuxserver image adds the Plex user to the device's group on start.
   Enable it in Plex under *Settings → Transcoder → Use hardware
   acceleration when available*.
+
+## Updates
+
+Watchtower updates the `plex` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `plex/**`
+change on `main`.

qbittorrent/README.md

@@ -75,3 +75,11 @@ rather than auto-updated. To update, set both values in
 `docker-compose.yml` from the new release (the SHA-256 is shown next to
 `vuetorrent.zip` on its GitHub release page, or `sha256sum vuetorrent.zip`)
 and redeploy. Older version folders stay in the volume (about 11 MB each).
+
+## Updates
+
+Not updated automatically: the qBittorrent image, the `alpine` helper and
+VueTorrent are all pinned, and none of them is opted in to Watchtower or
+Dependabot. Bump them by hand (see *Pinned version* and *VueTorrent*
+above). Dokploy redeploys the stack when files under `qbittorrent/**`
+change on `main`.

speedtest/README.md

@@ -30,3 +30,9 @@ Connects to `cloudflare-exposed`
 (must be created by the `cloudflared` service first).
 
 [speedtest-tracker]: https://github.com/alexjustesen/speedtest-tracker
+
+## Updates
+
+Watchtower updates the `speedtest` container automatically, following the
+`latest` tag. Dokploy redeploys the stack when files under `speedtest/**`
+change on `main`.

traccar/README.md

@@ -38,3 +38,9 @@ attaches its own network automatically on deploy.
 
 - Default ports: `25002` (mapped to 5013) and
   `25003` (mapped to 5023).
+
+## Updates
+
+Watchtower updates the `traccar` container automatically, following the
+`latest` tag. The MariaDB database is not part of this stack. Dokploy
+redeploys the stack when files under `traccar/**` change on `main`.

watchtower/README.md

@@ -24,6 +24,8 @@ Sends notifications via Telegram.
 
 ## Updates
 
-Watchtower updates itself too: its own container has the opt-in label.
-Services pinned to an exact version (for example Garage) are updated
-through Dependabot pull requests instead.
+Watchtower updates itself too, following the `latest` tag: its own
+container has the opt-in label. Services pinned to an exact version
+(for example Garage) are updated through Dependabot pull requests
+instead. Dokploy redeploys the stack when files under `watchtower/**`
+change on `main`.

wgdashboard/README.md

@@ -34,3 +34,9 @@ keys, so treat it and its backups as secrets.
 
 Declares no network. Needs the `NET_ADMIN` capability to manage the
 WireGuard interface.
+
+## Updates
+
+Watchtower updates the `wgdashboard` container automatically, following
+the `latest` tag. Dokploy redeploys the stack when files under
+`wgdashboard/**` change on `main`.