fix(help): align update subcommands and add backup descriptions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,6 @@
+# Webhook for update/backup notifications (n8n → Telegram)
+WEBHOOK_URL=https://n8n.example.com/webhook/your-webhook-id
+
+# Restic backup repository and password
+RESTIC_REPOSITORY=/mnt/hidrive/users/valknar/Backup/stacks
+RESTIC_PASSWORD=changeme

.gitignore

@@ -2,3 +2,4 @@
 .env
 *.sql
 *.log
+.data/

README.md

@@ -12,18 +12,79 @@ Each stack is independently deployable with its own `compose.yml` and `.env`. Al
 | `mailpit` | SMTP relay (no web UI) | mailpit |
 | `umami` | Web analytics | umami, db |
 | `immich` | Photo & video management | immich, ml, redis, db |
-| `affine` | Collaborative workspace & notes | affine, redis, db |
 | `n8n` | Workflow automation & notification relay | n8n, db |
 | `gitea` | Git hosting + CI runner | gitea, runner, db |
 | `coolify` | Deployment platform | coolify, realtime, redis, db |
 | `passbolt` | Password manager (GPG-encrypted, team sharing) | passbolt, db |
+| `code` | Browser-based VS Code IDE with Anthropic API access | code |
 
 ## Tools
 
-| Directory | Description |
+| File | Description |
 |---|---|
-| `_backup` | Daily restic backups to HiDrive (host script + systemd timer) |
+| `stacks.sh` | CLI to manage stacks, services, scaffolding, updates, and backups |
-| `_update` | Nightly image update check + prune (host script + systemd timer) |
+| `.env` | Root config: `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` (gitignored) |
+| `.env.example` | Template for the root `.env` |
+
+## stacks.sh
+
+`stacks.sh` is the primary management CLI. It wraps `docker compose` with glob-based multi-stack targeting, manages the update and backup systemd services, scaffolds new stacks, and generates shell completions.
+
+```bash
+./stacks.sh help
+```
+
+**Stack commands** — all accept one or more stack names or glob patterns (omit for all stacks):
+
+```bash
+./stacks.sh ls                        # list all stacks with live container status
+./stacks.sh ps gitea                  # container status table
+./stacks.sh up                        # start all stacks
+./stacks.sh up gitea traefik          # start specific stacks
+./stacks.sh down 'g*'                 # stop stacks matching glob
+./stacks.sh restart 'g*,traefik'      # glob + exact name, comma-separated
+./stacks.sh pull --parallel           # pull all images in parallel
+./stacks.sh logs -f gitea             # follow logs
+./stacks.sh logs -n 100 gitea n8n    # tail multiple stacks
+./stacks.sh exec gitea gitea gitea admin user list  # exec in container
+./stacks.sh run passbolt passbolt bin/cake passbolt healthcheck
+```
+
+**Service management** (reads `WEBHOOK_URL`, `RESTIC_REPOSITORY`, `RESTIC_PASSWORD` from root `.env`):
+
+```bash
+./stacks.sh update install     # write & enable systemd update timer
+./stacks.sh update run         # run update now
+./stacks.sh update status      # show timer/service status
+./stacks.sh update logs        # show journal logs
+
+./stacks.sh backup install     # write & enable systemd backup timer
+./stacks.sh backup run         # run backup now (auto-detects <stack>_db containers)
+./stacks.sh backup snapshots   # list restic snapshots
+```
+
+**Scaffold a new stack:**
+
+```bash
+./stacks.sh new myapp                      # basic stack with Traefik labels
+./stacks.sh new myapp --db postgres        # with Postgres service
+./stacks.sh new myapp --db postgres --redis  # with Postgres + Redis
+./stacks.sh new myapp --no-traefik         # expose port instead of Traefik
+```
+
+Generates `compose.yml` (with healthchecks, `../.data/` volumes, Traefik labels) and `.env.example`.
+
+**Shell completion:**
+
+```bash
+# Dynamic — discovers stacks at tab-complete time (default)
+./stacks.sh completion zsh --install
+
+# Static — bakes current stack list in; useful on the VPS
+./stacks.sh completion zsh --static --install
+```
+
+**Global flags:** `--dry-run`, `--parallel`, `--verbose`, `--quiet`
 
 ## Deployment
 
@@ -44,60 +105,36 @@ All stacks share the external `falcon_network` Docker network for inter-service
 
 ## Backup
 
-The `_backup` stack runs a daily restic backup at 3:00 AM. It dumps all Postgres databases, then backs up the entire `.data/` directory to HiDrive. Retention: 7 daily, 4 weekly, 6 monthly snapshots. Notifications go to Telegram via n8n.
+Runs daily at 3:00 AM via a systemd timer. Detects Postgres databases automatically by convention (`<stack>_db` container, user `<stack>`, database `<stack>`), dumps each one, then runs a full restic backup of `.data/`. Retention: 7 daily, 4 weekly, 6 monthly. Notifications go to Telegram via n8n.
 
 ```bash
-# Deploy backup stack
+# First-time setup on VPS
-rsync -avz _backup/ vps:~/stacks/_backup/
+cp .env.example .env && $EDITOR .env        # set RESTIC_REPOSITORY, RESTIC_PASSWORD, WEBHOOK_URL
+source .env && restic init                  # initialise restic repo
 
-# Initialize restic repo (first time only)
+./stacks.sh backup install   # write & enable systemd unit + timer
-ssh vps 'source ~/stacks/_backup/.env && restic init -r /mnt/hidrive/users/valknar/Backup/stacks'
+./stacks.sh backup run       # test run
-
+./stacks.sh backup snapshots # list snapshots
-# Install systemd units
+./stacks.sh backup status    # timer/service status
-ssh vps 'ln -sf ~/stacks/_backup/stacks-backup.service /etc/systemd/system/ && \
+./stacks.sh backup logs      # journald logs
-         ln -sf ~/stacks/_backup/stacks-backup.timer /etc/systemd/system/ && \
-         systemctl daemon-reload && systemctl enable --now stacks-backup.timer'
-
-# Manual test run
-ssh vps '~/stacks/_backup/backup.sh'
-
-# Check timer status
-ssh vps 'systemctl status stacks-backup.timer'
-
-# View snapshots
-ssh vps 'source ~/stacks/_backup/.env && restic -r /mnt/hidrive/users/valknar/Backup/stacks snapshots'
 ```
 
 ## Updates
 
-The `_update` script runs nightly at 2:00 AM. It pulls the latest image for every stack, recreates any containers whose image changed, prunes dangling images, and sends a Telegram notification via n8n.
+Runs nightly at 2:00 AM via a systemd timer. Pulls the latest image for every stack, recreates any container whose image changed, prunes dangling images, and sends a Telegram notification via n8n.
 
 ```bash
-# Deploy update stack
+./stacks.sh update install   # write & enable systemd unit + timer
-rsync -avz _update/ vps:~/stacks/_update/
+./stacks.sh update run       # test run
-ssh vps 'chmod +x ~/stacks/_update/update.sh'
+./stacks.sh update status    # timer/service status
-
+./stacks.sh update logs      # journald logs
-# Install systemd units
-ssh vps 'ln -sf ~/stacks/_update/stacks-update.service /etc/systemd/system/ && \
-         ln -sf ~/stacks/_update/stacks-update.timer /etc/systemd/system/ && \
-         systemctl daemon-reload && systemctl enable --now stacks-update.timer'
-
-# Manual test run
-ssh vps '~/stacks/_update/update.sh'
-
-# Check timer status
-ssh vps 'systemctl status stacks-update.timer'
 ```
 
 ## Notifications
 
-The update script and the backup script both POST to an n8n webhook, which forwards messages to Telegram.
+Both update and backup POST to an n8n webhook on completion, which forwards the message to Telegram.
 
-The webhook URL is set in:
+The webhook URL is set via `WEBHOOK_URL` in the root `.env`. Both services point to the same n8n workflow at `https://n8n.pivoine.art`, which accepts `{ "message": "...", "color": "..." }` and forwards it to Telegram.
-- `_backup/.env` → `WEBHOOK_URL`
-- `_update/.env` → `WEBHOOK_URL`
-
-Both point to the same n8n workflow at `https://n8n.pivoine.art`. The workflow accepts `{ "message": "..." }` and forwards it to Telegram.
 
 ## Data
 

_backup/.env.example

@@ -1,3 +0,0 @@
-RESTIC_REPOSITORY=/mnt/hidrive/users/valknar/Backup/stacks
-RESTIC_PASSWORD=change_me
-WEBHOOK_URL=https://n8n.example.com/webhook/change_me

_backup/backup.sh

@@ -1,84 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-STACKS_DIR="$(dirname "$SCRIPT_DIR")"
-DATA_DIR="$STACKS_DIR/.data"
-DUMP_DIR="$DATA_DIR/backup/dumps"
-LOG_FILE="$SCRIPT_DIR/backup.log"
-
-# Load environment
-set -a
-source "$SCRIPT_DIR/.env"
-set +a
-
-export RESTIC_REPOSITORY RESTIC_PASSWORD
-
-log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
-
-notify() {
-  local color="$1" text="$2"
-  curl -sf -o /dev/null -X POST "$WEBHOOK_URL" \
-    -H 'Content-Type: application/json' \
-    -d "{\"message\":\"$text\",\"color\":\"$color\"}"
-}
-
-# Truncate log on each run
-: > "$LOG_FILE"
-
-log "Starting backup"
-
-# --- Postgres dumps ---
-mkdir -p "$DUMP_DIR"
-
-declare -A DATABASES=(
-  [umami_db]="umami:umami"
-  [affine_db]="affine:affine"
-  [gitea_db]="gitea:gitea"
-  [n8n_db]="n8n:n8n"
-  [immich_db]="immich:immich"
-  [coolify_db]="coolify:coolify"
-  [passbolt_db]="passbolt:passbolt"
-)
-
-dump_errors=()
-for container in "${!DATABASES[@]}"; do
-  IFS=: read -r user db <<< "${DATABASES[$container]}"
-  log "Dumping $db from $container"
-  if docker exec "$container" pg_dump -U "$user" "$db" > "$DUMP_DIR/$db.sql" 2>>"$LOG_FILE"; then
-    log "  OK ($(du -h "$DUMP_DIR/$db.sql" | cut -f1))"
-  else
-    log "  FAILED: $container"
-    dump_errors+=("$db")
-  fi
-done
-
-if [ ${#dump_errors[@]} -gt 0 ]; then
-  log "WARNING: Failed dumps: ${dump_errors[*]}"
-fi
-
-# --- Restic backup ---
-log "Running restic backup"
-if ! restic backup "$DATA_DIR" --tag stacks 2>&1 | tee -a "$LOG_FILE"; then
-  log "FATAL: restic backup failed"
-  notify "#cc0000" "❌ **Backup failed** — restic backup error. Check \`$LOG_FILE\`."
-  exit 1
-fi
-
-# --- Restic prune ---
-log "Pruning old snapshots"
-if ! restic forget --prune --keep-daily 7 --keep-weekly 4 --keep-monthly 6 2>&1 | tee -a "$LOG_FILE"; then
-  log "WARNING: restic forget failed"
-fi
-
-# --- Summary ---
-snapshot_info=$(restic snapshots --latest 1 --compact 2>/dev/null | tail -3 | head -1)
-repo_stats=$(restic stats 2>/dev/null | grep "Total Size" || true)
-
-summary="✅ **Backup complete**"
-[ ${#dump_errors[@]} -gt 0 ] && summary+="\n⚠️ Failed dumps: ${dump_errors[*]}"
-summary+="\nLatest: \`$snapshot_info\`"
-[ -n "$repo_stats" ] && summary+="\nRepo: $repo_stats"
-
-notify "#36a64f" "$summary"
-log "Backup complete"

_backup/stacks-backup.service

@@ -1,10 +0,0 @@
-[Unit]
-Description=Backup stacks data to HiDrive via restic
-After=network-online.target docker.service
-Wants=network-online.target
-
-[Service]
-Type=oneshot
-User=root
-ExecStart=/root/stacks/_backup/backup.sh
-Environment=HOME=/root

_backup/stacks-backup.timer

@@ -1,9 +0,0 @@
-[Unit]
-Description=Daily stacks backup at 3:00 AM
-
-[Timer]
-OnCalendar=*-*-* 03:00:00 Europe/Amsterdam
-Persistent=true
-
-[Install]
-WantedBy=timers.target

_update/.env.example

@@ -1 +0,0 @@
-WEBHOOK_URL=https://n8n.example.com/webhook/change_me

_update/stacks-update.service

@@ -1,10 +0,0 @@
-[Unit]
-Description=Docker stacks image update
-After=network-online.target docker.service
-Wants=network-online.target
-
-[Service]
-Type=oneshot
-User=root
-ExecStart=/root/stacks/_update/update.sh
-Environment=HOME=/root

_update/stacks-update.timer

@@ -1,9 +0,0 @@
-[Unit]
-Description=Daily Docker stacks image update at 2:00 AM
-
-[Timer]
-OnCalendar=*-*-* 02:00:00 Europe/Amsterdam
-Persistent=true
-
-[Install]
-WantedBy=timers.target

_update/update.sh

@@ -1,56 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-STACKS_DIR="$(dirname "$SCRIPT_DIR")"
-LOG_FILE="$SCRIPT_DIR/update.log"
-
-set -a; source "$SCRIPT_DIR/.env"; set +a
-
-log()    { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
-notify() {
-  local color="$1" text="$2"
-  curl -sf -o /dev/null -X POST "$WEBHOOK_URL" \
-    -H 'Content-Type: application/json' \
-    -d "{\"message\":\"$text\",\"color\":\"$color\"}"
-}
-
-: > "$LOG_FILE"
-log "Starting image update check"
-
-updated=(); failed=()
-
-for stack_dir in "$STACKS_DIR"/*/; do
-  stack=$(basename "$stack_dir")
-  [[ "$stack" == _* ]] && continue
-  [[ ! -f "$stack_dir/compose.yml" ]] && continue
-
-  log "Checking $stack"
-  cd "$stack_dir"
-  pull_output=$(docker compose pull 2>&1 | tee -a "$LOG_FILE")
-
-  if echo "$pull_output" | grep -q " Pulled$"; then
-    log "  Updates found — recreating containers"
-    if docker compose up -d 2>&1 | tee -a "$LOG_FILE"; then
-      updated+=("$stack")
-    else
-      log "  FAILED to recreate $stack"
-      failed+=("$stack")
-    fi
-  else
-    log "  Up to date"
-  fi
-done
-
-log "Pruning dangling images"
-docker image prune -f 2>&1 | tee -a "$LOG_FILE"
-
-if [ ${#updated[@]} -eq 0 ] && [ ${#failed[@]} -eq 0 ]; then
-  notify "#36a64f" "✅ **Update check complete** — all images up to date"
-elif [ ${#failed[@]} -gt 0 ]; then
-  notify "#cc0000" "❌ **Update failed**\nUpdated: ${updated[*]:-none}\nFailed: ${failed[*]}"
-else
-  notify "#36a64f" "✅ **Updates applied**\nStacks: ${updated[*]}"
-fi
-
-log "Update check complete"

affine/.env.example

@@ -1,11 +0,0 @@
-TRAEFIK_HOST=affine.example.com
-NETWORK_NAME=falcon_network
-DB_USERNAME=affine
-DB_PASSWORD=change_me
-DB_DATABASE=affine
-MAILER_HOST=mailpit
-MAILER_PORT=1025
-MAILER_USER=affine
-MAILER_PASSWORD=affine
-MAILER_SENDER=affine@example.com
-MAILER_IGNORE_TLS=true

affine/compose.yml

@@ -1,87 +0,0 @@
-services:
-  affine:
-    image: ghcr.io/toeverything/affine:stable
-    container_name: affine
-    env_file: .env
-    environment:
-      REDIS_SERVER_HOST: redis
-      DATABASE_URL: postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
-      AFFINE_SERVER_EXTERNAL_URL: https://${TRAEFIK_HOST}
-      AFFINE_INDEXER_ENABLED: "false"
-    volumes:
-      - ../.data/affine/storage:/root/.affine/storage
-      - ../.data/affine/config:/root/.affine/config
-    depends_on:
-      redis:
-        condition: service_healthy
-      postgres:
-        condition: service_healthy
-      affine_migration:
-        condition: service_completed_successfully
-    restart: unless-stopped
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.middlewares.affine-redirect-web-secure.redirectscheme.scheme=https"
-      - "traefik.http.routers.affine-web.middlewares=affine-redirect-web-secure"
-      - "traefik.http.routers.affine-web.rule=Host(`${TRAEFIK_HOST}`)"
-      - "traefik.http.routers.affine-web.entrypoints=web"
-      - "traefik.http.routers.affine-web-secure.rule=Host(`${TRAEFIK_HOST}`)"
-      - "traefik.http.routers.affine-web-secure.tls.certresolver=resolver"
-      - "traefik.http.routers.affine-web-secure.entrypoints=web-secure"
-      - "traefik.http.routers.affine-web-secure.middlewares=security-headers@file,no-index@file"
-      - "traefik.http.services.affine-web-secure.loadbalancer.server.port=3010"
-      - "traefik.docker.network=${NETWORK_NAME}"
-    networks:
-      - compose_network
-  affine_migration:
-    image: ghcr.io/toeverything/affine:stable
-    container_name: affine_migration
-    env_file: .env
-    command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
-    environment:
-      REDIS_SERVER_HOST: redis
-      DATABASE_URL: postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
-      AFFINE_INDEXER_ENABLED: "false"
-    volumes:
-      - ../.data/affine/storage:/root/.affine/storage
-      - ../.data/affine/config:/root/.affine/config
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    networks:
-      - compose_network
-  redis:
-    image: redis
-    container_name: affine_redis
-    healthcheck:
-      test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-    networks:
-      - compose_network
-  postgres:
-    image: pgvector/pgvector:pg16
-    container_name: affine_db
-    environment:
-      POSTGRES_USER: ${DB_USERNAME}
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-      POSTGRES_DB: ${DB_DATABASE:-affine}
-      POSTGRES_INITDB_ARGS: --data-checksums
-    volumes:
-      - ../.data/affine/db:/var/lib/postgresql/data
-    healthcheck:
-      test: ['CMD', 'pg_isready', '-U', "${DB_USERNAME}", '-d', "${DB_DATABASE:-affine}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-    networks:
-      - compose_network
-networks:
-  compose_network:
-    name: ${NETWORK_NAME}
-    external: true

code/.env.example

@@ -0,0 +1,8 @@
+TRAEFIK_HOST=code.example.com
+NETWORK_NAME=falcon_network
+TIMEZONE=Europe/Amsterdam
+DOCKER_USER=coder
+PUID=1000
+PGID=1000
+PASSWORD=changeme
+ANTHROPIC_API_KEY=

code/compose.yml

@@ -0,0 +1,32 @@
+services:
+  code:
+    image: codercom/code-server:latest
+    container_name: code
+    user: "${PUID:-1000}:${PGID:-1000}"
+    environment:
+      TZ: ${TIMEZONE:-Europe/Amsterdam}
+      DOCKER_USER: ${DOCKER_USER:-coder}
+      PASSWORD: ${PASSWORD}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+    volumes:
+      - ../.data/code:/home/coder
+    restart: always
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.middlewares.code-redirect-web-secure.redirectscheme.scheme=https"
+      - "traefik.http.routers.code-web.middlewares=code-redirect-web-secure"
+      - "traefik.http.routers.code-web.rule=Host(`${TRAEFIK_HOST}`)"
+      - "traefik.http.routers.code-web.entrypoints=web"
+      - "traefik.http.routers.code-web-secure.rule=Host(`${TRAEFIK_HOST}`)"
+      - "traefik.http.routers.code-web-secure.tls.certresolver=resolver"
+      - "traefik.http.routers.code-web-secure.entrypoints=web-secure"
+      - "traefik.http.routers.code-web-secure.middlewares=security-headers@file,no-index@file"
+      - "traefik.http.services.code-web-secure.loadbalancer.server.port=8080"
+      - "traefik.docker.network=${NETWORK_NAME}"
+    networks:
+      - compose_network
+
+networks:
+  compose_network:
+    name: ${NETWORK_NAME}
+    external: true

gitea/.env.example

@@ -1,3 +1,5 @@
 TRAEFIK_HOST=dev.example.com
 NETWORK_NAME=falcon_network
 RUNNER_TOKEN=change_me
+EMAIL_FROM=gitea@pivoine.art
+EMAIL_USER=Gitea

gitea/.gitignore

@@ -0,0 +1 @@
+.env

gitea/compose.yml

@@ -25,6 +25,8 @@ services:
       GITEA__mailer__PROTOCOL: smtp
       GITEA__mailer__SMTP_ADDR: mailpit
       GITEA__mailer__SMTP_PORT: 1025
+      GITEA__mailer__FROM: ${EMAIL_FROM}
+      GITEA__mailer__USER: ${EMAIL_USER}
       GITEA__service__DISABLE_REGISTRATION: "true"
       GITEA__service__REQUIRE_SIGNIN_VIEW: "false"
       GITEA__service__ENABLE_NOTIFY_MAIL: "true"
@@ -41,6 +43,7 @@ services:
       - ../.data/gitea/config:/etc/gitea
       - ./css:/data/gitea/public/assets/css:ro
       - ./img:/data/gitea/public/assets/img:ro
+      - ./templates/custom:/data/gitea/templates/custom:ro
       - /etc/localtime:/etc/localtime:ro
     depends_on:
       db:

gitea/templates/custom/header.tmpl

@@ -0,0 +1,3 @@
+{{if and .RunModeIsProd (not .IsSigned)}}
+<script defer src="https://umami.pivoine.art/script.js" data-website-id="eee7e810-116b-408a-a46d-f51dcec217c2"></script>
+{{end}}

passbolt/.env.example

@@ -1,2 +1,4 @@
 TRAEFIK_HOST=passbolt.example.com
 NETWORK_NAME=falcon_network
+EMAIL_FROM=passbolt@pivoine.art
+EMAIL_USER=Passbolt

passbolt/compose.yml

@@ -18,8 +18,8 @@ services:
       EMAIL_TRANSPORT_DEFAULT_HOST: mailpit
       EMAIL_TRANSPORT_DEFAULT_PORT: "1025"
       EMAIL_TRANSPORT_DEFAULT_TLS: "false"
-      EMAIL_DEFAULT_FROM: passbolt@pivoine.art
+      EMAIL_DEFAULT_FROM: ${EMAIL_FROM}
-      EMAIL_DEFAULT_FROM_NAME: Passbolt
+      EMAIL_DEFAULT_FROM_NAME: ${EMAIL_USER}
     volumes:
       - ../.data/passbolt/gpg:/etc/passbolt/gpg
       - ../.data/passbolt/jwt:/etc/passbolt/jwt