From 27b09e18e354e9d50554de9f1b1db3c9e9e86ea6 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Mon, 20 Jul 2026 21:42:26 -0400
Subject: [PATCH] docs: add a copy-paste deploy compose to the README

New "Deploy (self-host)" section with a complete app + Postgres stack using
the published image, restart policies, a healthcheck, the /var/thoughtsync
data volume, and the single required env (THOUGHTSYNC_DATABASE_URL). Notes:
first account is admin, optional SECRET_KEY, auto wait+migrate on boot, and
the image-tag scheme (:latest / :dev / :<sha>).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 7445a49..27134d3 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,56 @@ Or the **full production image** (SPA baked in) at http://localhost:5000:
 docker compose up --build
 ```
 
+## Deploy (self-host)
+
+A complete two-container stack (app + Postgres) you can copy and run. Save it as
+`docker-compose.yml`, change the two `CHANGE_ME` passwords (they must match), then
+`docker compose up -d`:
+
+```yaml
+services:
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: thoughtsync
+      POSTGRES_PASSWORD: CHANGE_ME          # change this
+      POSTGRES_DB: thoughtsync
+    volumes:
+      - thoughtsync-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U thoughtsync"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  app:
+    image: git.fabledsword.com/bvandeusen/thoughtsync:latest   # :dev for the current dev build
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      THOUGHTSYNC_DATABASE_URL: postgresql+asyncpg://thoughtsync:CHANGE_ME@db:5432/thoughtsync
+    volumes:
+      - thoughtsync-data:/var/thoughtsync   # uploaded images; omit if you don't use attachments
+    ports:
+      - "5000:5000"
+
+volumes:
+  thoughtsync-db:
+  thoughtsync-data:
+```
+
+Then open `http://<host>:5000` and register — **the first account becomes the admin**.
+
+- **Only `THOUGHTSYNC_DATABASE_URL` is required.** `THOUGHTSYNC_SECRET_KEY` is optional; if
+  unset, a signing key is generated and persisted in the database (sessions survive restarts).
+- Uploaded images live under the `thoughtsync-data` volume at `/var/thoughtsync`.
+- The app waits for the database and runs migrations (`alembic upgrade head`) automatically on start.
+- **Image tags:** `:latest` (stable, built from `main`) · `:dev` (latest `dev` build) ·
+  `:<git-sha>` (immutable, for pinning / rollback).
+
 ## Milestones
 
 - **M0 — Foundation & Identity** ✅: Quart+Vue+Postgres skeleton, native auth,