Backend Phase A: foundation, migrations, Docker setup

- Go backend skeleton: config (caarlos0/env), slog JSON logging,
  pgxpool store, HTTP server with graceful shutdown.
- httpapi: render helpers, Problem errors, middleware chain
  (requestID / logging / recover / CORS), /healthz and /readyz.
- Migrations: full initial schema (users, sessions, lists,
  list_members, items, op_log SOURCE OF TRUTH, item_names) +
  golang-migrate runner binary using source/iofs (embedded).
- Docker: multi-stage Dockerfile (Go 1.26 -> distroless nonroot),
  builds both server and migrate binaries.
- deploy: docker-compose (caddy + backend + migrate + postgres:16),
  Caddyfile (auto-HTTPS), .env.example, pg extensions init script.
- AGENTS.md: project context + roadmap for AI agents.

Verified: image builds, both binaries run in container (smoke test).

deploy/.env.example

@@ -0,0 +1,44 @@
+# ===========================================================================
+# mitbringsl backend configuration
+# Copy this file to ".env" and adjust the values.
+#   cp .env.example .env
+# ===========================================================================
+
+# --- General app behavior ---
+APP_ENV=production                  # development | production
+LOG_LEVEL=info                      # debug | info | warn | error
+
+# The externally reachable base URL (scheme + host, no trailing slash).
+# Must match the domain you serve Caddy on. Used for OIDC redirect URIs etc.
+PUBLIC_BASE_URL=https://mitbringsl.example.com
+
+# The public domain Caddy serves. Used to set the Caddy site address.
+PUBLIC_DOMAIN=mitbringsl.example.com
+
+# --- PostgreSQL ---
+POSTGRES_USER=app
+# CHOOSE A STRONG PASSWORD (only required for first DB init, then stored).
+POSTGRES_PASSWORD=change-me-to-a-long-random-string
+POSTGRES_DB=appdb
+# DATABASE_URL is composed by docker-compose from the values above.
+
+# --- Session tokens ---
+# TTL of the opaque session token issued after login.
+SESSION_TOKEN_TTL=720h              # 30 days
+
+# --- OIDC: Google (optional) ---
+OIDC_GOOGLE_ENABLED=false
+# The OAuth client ID you created in Google Cloud Console (Audience the
+# backend accepts). No client_secret needed: the Android app performs the
+# code exchange itself and only sends the id_token to the backend.
+OIDC_GOOGLE_CLIENT_ID=
+OIDC_GOOGLE_ISSUER=https://accounts.google.com
+
+# --- OIDC: Generic provider (Keycloak, Authentik, Dex, ...; optional) ---
+OIDC_GENERIC_ENABLED=false
+OIDC_GENERIC_ISSUER=                # e.g. https://idp.example.com/realms/main
+OIDC_GENERIC_CLIENT_ID=             # audience the backend accepts
+
+# --- CORS (only relevant for browser clients; Android doesn't need it) ---
+# Comma-separated list of allowed origins, e.g. https://app.example.com
+CORS_ALLOWED_ORIGINS=

deploy/Caddyfile

@@ -0,0 +1,31 @@
+# Caddyfile for mitbringsl.
+# Caddy automatically obtains and renews a Let's Encrypt certificate when the
+# site address is a real domain. For local development it falls back to an
+# internal CA / self-signed cert automatically.
+{
+	# email you@example.com   # optional, for ACME account
+}
+
+{$SITE_ADDRESS:localhost} {
+	reverse_proxy backend:8080 {
+		header_up X-Real-IP {remote_host}
+		header_up X-Forwarded-For {remote_host}
+	}
+
+	# Useful default headers
+	header {
+		Strict-Transport-Security "max-age=31536000"
+		X-Content-Type-Options "nosniff"
+		Referrer-Policy "no-referrer"
+	}
+
+	# Health endpoint passthrough already handled by backend; keep it simple.
+	request_body {
+		max_size 2MB
+	}
+
+	log {
+		output stdout
+		format console
+	}
+}

deploy/db/init/001_extensions.sql

@@ -0,0 +1,4 @@
+-- Runs only on first DB init (docker-entrypoint-initdb.d).
+-- Extensions used by the application.
+CREATE EXTENSION IF NOT EXISTS pgcrypto;   -- gen_random_uuid()
+CREATE EXTENSION IF NOT EXISTS pg_trgm;    -- trigram fuzzy search for autocomplete

deploy/docker-compose.yml

@@ -0,0 +1,102 @@
+# Self-hosted deployment for mitbringsl.
+#
+#   cp .env.example .env   # fill in secrets + domains
+#   docker compose up -d --build
+#
+# Services:
+#   caddy    public reverse proxy with automatic HTTPS (Let's Encrypt)
+#   backend  mitbringsl Go API (image builds server + migrate binaries)
+#   migrate  one-shot migration runner, must finish before backend starts
+#   db       PostgreSQL 16
+name: mitbringsl
+
+x-backend-image: &backend-image
+  image: mitbringsl-backend
+  build:
+    context: ../backend
+    dockerfile: Dockerfile
+
+x-app-env: &appenv
+  APP_ENV: ${APP_ENV:-production}
+  LOG_LEVEL: ${LOG_LEVEL:-info}
+  DATABASE_URL: postgres://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-appdb}?sslmode=disable
+
+services:
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      POSTGRES_DB: ${POSTGRES_DB:-appdb}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./db/init:/docker-entrypoint-initdb.d:ro   # runs on first init only
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app} -d ${POSTGRES_DB:-appdb}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    networks: [appnet]
+    # Only expose the DB to the host for local debugging; remove in prod.
+    # ports:
+    #   - "5432:5432"
+
+  migrate:
+    <<: *backend-image
+    restart: "no"
+    command: ["/app/migrate", "up"]
+    environment:
+      <<: *appenv
+    depends_on:
+      db:
+        condition: service_healthy
+    networks: [appnet]
+
+  backend:
+    <<: *backend-image
+    restart: unless-stopped
+    environment:
+      <<: *appenv
+      HTTP_ADDR: ":8080"
+      PUBLIC_BASE_URL: ${PUBLIC_BASE_URL:-http://localhost:8080}
+      SESSION_TOKEN_TTL: ${SESSION_TOKEN_TTL:-720h}
+      # OIDC (all optional)
+      OIDC_GOOGLE_ENABLED: ${OIDC_GOOGLE_ENABLED:-false}
+      OIDC_GOOGLE_CLIENT_ID: ${OIDC_GOOGLE_CLIENT_ID:-}
+      OIDC_GOOGLE_ISSUER: ${OIDC_GOOGLE_ISSUER:-https://accounts.google.com}
+      OIDC_GENERIC_ENABLED: ${OIDC_GENERIC_ENABLED:-false}
+      OIDC_GENERIC_ISSUER: ${OIDC_GENERIC_ISSUER:-}
+      OIDC_GENERIC_CLIENT_ID: ${OIDC_GENERIC_CLIENT_ID:-}
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-}
+    expose: ["8080"]
+    depends_on:
+      db:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
+    networks: [appnet]
+
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"        # ACME HTTP-01 challenge + redirect
+      - "443:443"
+      - "443:443/udp"  # HTTP/3
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - backend
+    networks: [appnet]
+
+volumes:
+  pgdata:
+  caddy_data:
+  caddy_config:
+
+networks:
+  appnet: