feat(selfhost): one-command self-host package (epic 6d)

- docker-compose.selfhost.yml pulls the published image (forge.b1fr0st.eu/peter/siftlode) with a
  bundled Postgres — no source build on the operator's host.
- install.sh / install.ps1 generate the four required secrets (.env: POSTGRES_PASSWORD, SECRET_KEY,
  a valid Fernet TOKEN_ENCRYPTION_KEY, OAUTH_REDIRECT_URL), start the stack, and print the first-run
  setup-wizard URL. Everything else is configured in the web wizard.
- docs/self-hosting.md: the copy-paste playbook (get the files, run the installer, finish in the
  wizard, optional Google/SMTP, HTTPS/reverse-proxy, updates + backups).
- Verified end-to-end: a fresh install from the published image boots into setup mode and serves
  the wizard.

docker-compose.selfhost.yml

@@ -0,0 +1,67 @@
+# Self-hosting Siftlode — pulls the prebuilt image, no source build needed.
+#
+#   1. Run ./install.sh  (or install.ps1 on Windows) once — it generates a .env with secrets.
+#   2. docker compose -f docker-compose.selfhost.yml up -d
+#   3. Open the setup wizard at the URL printed in the logs:
+#        docker compose -f docker-compose.selfhost.yml logs api | grep SETUP
+#
+# The .env only needs four values (the install script generates all of them):
+#   POSTGRES_PASSWORD, SECRET_KEY, TOKEN_ENCRYPTION_KEY, OAUTH_REDIRECT_URL
+# Everything else — the admin account, Google sign-in, SMTP — is set in the web wizard on
+# first run. See docs/self-hosting.md.
+
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-subfeed}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set (run install.sh)}
+      POSTGRES_DB: ${POSTGRES_DB:-subfeed}
+    volumes:
+      - siftlode_pgdata:/var/lib/postgresql/data
+    networks: [internal]
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-subfeed} -d ${POSTGRES_DB:-subfeed}"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+    restart: unless-stopped
+
+  api:
+    image: forge.b1fr0st.eu/peter/siftlode:${IMAGE_TAG:-latest}
+    env_file:
+      - .env
+    environment:
+      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-subfeed}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-subfeed}
+      # This instance owns the background scheduler (single writer).
+      SCHEDULER_ENABLED: "true"
+    depends_on:
+      db:
+        condition: service_healthy
+    networks: [internal]
+    ports:
+      # Reachable on the host's LAN at http://<host>:8080. Put a reverse proxy (Caddy/Nginx) in
+      # front for HTTPS / public exposure — and set OAUTH_REDIRECT_URL to the https URL.
+      - "${HTTP_PORT:-8080}:8000"
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/healthz').status==200 else 1)"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    restart: unless-stopped
+
+volumes:
+  siftlode_pgdata:
+
+networks:
+  internal:

docs/self-hosting.md

@@ -0,0 +1,97 @@
+# Self-hosting Siftlode
+
+Run your own private Siftlode instance with Docker. You don't need the source code — the app runs
+from a prebuilt image, and everything user-facing (your admin account, Google sign-in, email) is
+configured in a web wizard on first start. There's no editing of config files by hand.
+
+## What you need
+
+- A machine with **Docker** and the **Docker Compose plugin** (Docker Desktop on Windows/macOS,
+  or Docker Engine on Linux).
+- A few hundred MB of disk and ~1 GB RAM free.
+- Optional: a domain name + reverse proxy if you want HTTPS / public access (see below).
+
+## 1. Get the files
+
+Download these into a new, empty folder:
+
+- `docker-compose.selfhost.yml`
+- `install.sh` (Linux/macOS) **or** `install.ps1` (Windows)
+
+The app image is published at `forge.b1fr0st.eu/peter/siftlode` (public — no login to pull).
+
+## 2. Run the installer
+
+**Linux / macOS:**
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+./install.ps1
+```
+
+The installer asks for the **public URL** where the instance will be reached (just press Enter for
+`http://localhost:8080` to try it locally). It then:
+
+- generates the secrets it needs (`SECRET_KEY`, `TOKEN_ENCRYPTION_KEY`, a database password) into a
+  local `.env` file — keep that file private,
+- pulls the image and starts the app + database,
+- prints the **setup wizard URL**, which looks like `…/setup?token=…`.
+
+## 3. Finish in the web wizard
+
+Open the printed setup URL in your browser. The one-time token in it means only you (with access to
+the server logs) can run setup. Then click through:
+
+1. **Admin account** — your email + a password. This is how you'll sign in.
+2. **Google sign-in** *(optional)* — paste a Google OAuth client ID + secret to enable "Sign in with
+   Google" and pulling your YouTube subscriptions. Skip it to use email + password only.
+3. **Email / SMTP** *(optional)* — an SMTP server so the app can send verification and notification
+   emails. Skip it — without email, new registrations are simply approved by you (the admin) instead.
+4. **Finish** — the wizard disappears, the instance is now configured, and you land on the sign-in
+   page. Log in with the admin account you just created.
+
+That's it. You can change any of the optional settings later under the admin **Configuration** page.
+
+> The setup wizard only exists until you finish it. After that, the setup routes are disabled and
+> the token is invalidated — there's no setup surface left on a configured instance.
+
+## Getting a Google OAuth client (optional)
+
+Only needed for "Sign in with Google" / YouTube access. In the
+[Google Cloud Console](https://console.cloud.google.com/): create a project → **APIs & Services →
+Credentials → Create credentials → OAuth client ID** → *Web application*. Add your instance's
+`…/auth/callback` URL as an **Authorized redirect URI**, then copy the **client ID** and **secret**
+into the wizard's Google step. (Enable the **YouTube Data API v3** for the project too.)
+
+## HTTPS / public access
+
+The app is served on port `8080` over plain HTTP, which is fine for a LAN or a quick trial. For
+public access, put a reverse proxy (Caddy, Nginx, Traefik…) in front to terminate TLS, and set the
+**public URL** in the installer to your `https://…` address (this also marks the session cookie
+secure). If you've already run the installer, edit `OAUTH_REDIRECT_URL` in `.env` to the https
+callback URL and `docker compose -f docker-compose.selfhost.yml up -d`.
+
+## Day-to-day
+
+```bash
+# Update to the latest release
+docker compose -f docker-compose.selfhost.yml pull
+docker compose -f docker-compose.selfhost.yml up -d
+
+# Logs / status
+docker compose -f docker-compose.selfhost.yml logs -f api
+docker compose -f docker-compose.selfhost.yml ps
+
+# Stop
+docker compose -f docker-compose.selfhost.yml down
+```
+
+Your data (accounts, subscriptions, playlists, the video catalog) lives in the `siftlode_pgdata`
+Docker volume — back that up to keep your instance's state. Database migrations run automatically
+when the app starts, so updating is just pull + up.

install.ps1

@@ -0,0 +1,52 @@
+# Siftlode self-host installer (Windows / PowerShell). Generates secrets into .env, starts the
+# stack from the prebuilt image, and prints the first-run setup-wizard URL. Re-running is safe: an
+# existing .env is left untouched. Requires Docker Desktop (with the compose plugin).
+$ErrorActionPreference = "Stop"
+$Port = if ($env:HTTP_PORT) { $env:HTTP_PORT } else { "8080" }
+
+function New-RandBytes([int]$n) {
+  $b = New-Object byte[] $n
+  $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
+  $rng.GetBytes($b)
+  return $b
+}
+
+if (Test-Path .env) {
+  Write-Host ".env already exists — leaving it untouched (delete it to re-generate)."
+} else {
+  $url = Read-Host "Public URL where this instance will be reached [http://localhost:$Port]"
+  if ([string]::IsNullOrWhiteSpace($url)) { $url = "http://localhost:$Port" }
+  $url = $url.TrimEnd('/')
+
+  $secretKey = (New-RandBytes 32 | ForEach-Object { $_.ToString("x2") }) -join ""
+  $fernet = [Convert]::ToBase64String((New-RandBytes 32)).Replace('+', '-').Replace('/', '_')
+  $pgPass = (New-RandBytes 16 | ForEach-Object { $_.ToString("x2") }) -join ""
+
+  @"
+# Generated by install.ps1 — keep secret, never commit. Re-run after deleting to reset.
+POSTGRES_PASSWORD=$pgPass
+SECRET_KEY=$secretKey
+TOKEN_ENCRYPTION_KEY=$fernet
+OAUTH_REDIRECT_URL=$url/auth/callback
+"@ | Set-Content -Path .env -Encoding ascii
+  Write-Host "Wrote .env (secrets generated)."
+}
+
+Write-Host "Pulling and starting Siftlode..."
+docker compose -f docker-compose.selfhost.yml pull
+docker compose -f docker-compose.selfhost.yml up -d
+
+Write-Host "Waiting for the app to come up..."
+foreach ($i in 1..30) {
+  try { Invoke-WebRequest "http://localhost:$Port/healthz" -UseBasicParsing -TimeoutSec 3 | Out-Null; break } catch { Start-Sleep 2 }
+}
+
+Write-Host ""
+Write-Host "==================================================================="
+Write-Host " Siftlode is up. Open the first-run setup wizard at:"
+$logs = docker compose -f docker-compose.selfhost.yml logs api 2>$null
+$match = ($logs | Select-String -Pattern "https?://\S*setup\?token=[A-Za-z0-9_-]+" -AllMatches |
+  ForEach-Object { $_.Matches.Value } | Select-Object -Last 1)
+if ($match) { Write-Host "   $match" }
+else { Write-Host "   (not found yet — run: docker compose -f docker-compose.selfhost.yml logs api | Select-String 'setup?token=')" }
+Write-Host "==================================================================="

install.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Siftlode self-host installer (Linux/macOS). Generates secrets into .env, starts the stack from
+# the prebuilt image, and prints the first-run setup-wizard URL. Re-running is safe: an existing
+# .env is left untouched. Requires Docker (with the compose plugin) and openssl.
+set -euo pipefail
+
+COMPOSE="docker compose -f docker-compose.selfhost.yml"
+PORT="${HTTP_PORT:-8080}"
+
+if [ -f .env ]; then
+  echo ".env already exists — leaving it untouched (delete it to re-generate)."
+else
+  printf "Public URL where this instance will be reached [http://localhost:%s]: " "$PORT"
+  read -r URL
+  URL="${URL:-http://localhost:$PORT}"
+  URL="${URL%/}"
+
+  # Secrets — openssl only, no Python needed. The Fernet key is urlsafe base64 of 32 bytes.
+  SECRET_KEY="$(openssl rand -hex 32)"
+  TOKEN_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')"
+  POSTGRES_PASSWORD="$(openssl rand -hex 16)"
+
+  cat > .env <<EOF
+# Generated by install.sh — keep secret (chmod 600), never commit. Re-run after deleting to reset.
+POSTGRES_PASSWORD=$POSTGRES_PASSWORD
+SECRET_KEY=$SECRET_KEY
+TOKEN_ENCRYPTION_KEY=$TOKEN_ENCRYPTION_KEY
+OAUTH_REDIRECT_URL=$URL/auth/callback
+EOF
+  chmod 600 .env
+  echo "Wrote .env (secrets generated)."
+fi
+
+echo "Pulling and starting Siftlode…"
+$COMPOSE pull
+$COMPOSE up -d
+
+echo "Waiting for the app to come up…"
+for _ in $(seq 1 30); do
+  curl -fsS -o /dev/null "http://localhost:$PORT/healthz" 2>/dev/null && break
+  sleep 2
+done
+
+echo
+echo "==================================================================="
+echo " Siftlode is up. Open the first-run setup wizard at:"
+URL_LINE="$($COMPOSE logs api 2>/dev/null | grep -o 'http[s]*://[^ ]*setup?token=[A-Za-z0-9_-]*' | tail -1)"
+if [ -n "$URL_LINE" ]; then
+  echo "   $URL_LINE"
+else
+  echo "   (not found yet — run: $COMPOSE logs api | grep 'setup?token=')"
+fi
+echo "==================================================================="