Explain the SSL failure instead of just reporting it

A Postgres URL without an sslmode made lib/pq ask for TLS and die with
"SSL is not enabled on the server", which reads like a server fault when
it is really a connection-string default. The error now says what to
append, and the server retries briefly so a deploy is not marked
unhealthy just because Postgres was still starting.

The sync server URL also defaults to the hosted instance now, so a fresh
install needs no setup.

AGENTS.md

@@ -40,8 +40,16 @@ clicking an item copies it back to the clipboard.
   a global queue); only the store append hops back to main.
 - `Sources/Prompt/SyncService.swift` — optional sync client. Holds the group
   code and server URL in `UserDefaults` (`sync.code`, `sync.serverURL`,
-  `sync.version`), pushes the whole store as JSON, and polls every 5s.
+  `sync.version`). The URL defaults to `SyncService.defaultServerURL`
+  (`https://prompt.tzgyn.dev`); nothing is sent anywhere until a code exists,
+  because polling only runs when one is set. Pushes the whole store as JSON and
+  polls every 5s.
 - `Server/main.go` — the Go sync backend (single file, `net/http` + `lib/pq`).
+  Also ships `Server/Dockerfile` (static binary on distroless) and
+  `Server/README.md` (self-hosting). Logs one line per request, creates its
+  schema on startup, shuts down gracefully on SIGTERM so a redeploy cannot cut
+  off a push, and supports `-healthcheck` (pings local `/healthz`) so the
+  shell-less image needs no curl for its Docker `HEALTHCHECK`.
 
 ## Sync protocol
 
@@ -53,6 +61,7 @@ payload as opaque `JSONB`; it never parses note contents.
 | --- | --- |
 | `POST /api/codes` | Generates a unique code and inserts an empty group |
 | `GET /api/sync/{code}` | `{"version":N,"updatedAt":…,"data":{…}\|null}`, 404 if unknown |
+| `GET /api/sync/{code}/version` | `{"version":N}` — the cheap poll |
 | `PUT /api/sync/{code}` | Upserts the payload, returns the incremented version |
 | `GET /healthz` | Liveness |
 
@@ -60,6 +69,9 @@ Client rules:
 
 - Payload = `{sections, activeSectionID, images}`, where `images` maps a
   filename to base64 PNG so photos travel with the notes.
+- Polling is two-step: `GET /version` every 5s (tiny) and the full payload only
+  when the version moved. Fetching the payload unconditionally would re-download
+  every base64 photo every 5 seconds.
 - Version counter is server-owned; the client stores the last version it saw
   in `sync.version` and only applies a remote payload when `remote.version >
   lastVersion`.

README.md

@@ -58,17 +58,24 @@ PROMPT_SYNC_DATABASE_URL="postgres://localhost:5432/prompt_sync?sslmode=disable"
   go run .          # listens on :8080
 ```
 
-Then in the panel: click the sync icon, set the server URL (e.g.
-`http://192.168.1.10:8080` or an HTTPS host), and either **Generate Code** on
-the first Mac or paste the code into **Join** on the other.
+Or build the Docker image (`docker build -t prompt-sync Server/`) and point it
+at your own Postgres — see [Server/README.md](Server/README.md) for that and for
+deploying to a host.
+
+Then in the panel: click the sync icon (or Cmd+,), confirm the server URL, and
+either **Generate Code** on the first Mac or paste the code into **Join** on the
+other.
 
 Notes:
 
-- Both Macs must be able to reach the server. A LAN address or a Tailscale
-  hostname works; `localhost` only works if the server runs on the same Mac.
+- Sync defaults to `https://prompt.tzgyn.dev`; change it in the sync panel to
+  point at your own server. Both Macs must be able to reach it — a LAN address
+  or a Tailscale hostname works, and `localhost` only works if the server runs
+  on the same Mac. See [Server/README.md](Server/README.md) to deploy it.
 - Joining a group that already has notes replaces what's on that Mac.
-- The app polls every 5 seconds and pushes 1.5s after a change; last write
-  wins. Changes that came from the server are not echoed back.
+- The app polls every 5 seconds (a tiny version check) and pushes 1.5s after a
+  change; last write wins, and changes that came from the server are not echoed
+  back.
 - Verify sync from a terminal with `Prompt --sync-check`.
 
 ## Build from source

Server/.dockerignore

@@ -0,0 +1,4 @@
+.git
+prompt-sync
+prompt-sync-*
+*.md

Server/Dockerfile

@@ -0,0 +1,27 @@
+# Build stage: the server is pure Go (lib/pq is pure Go), so CGO is off and the
+# result is a static binary that runs on a shell-less base image.
+FROM golang:1.26-alpine AS build
+
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY *.go ./
+
+ARG TARGETOS
+ARG TARGETARCH
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags="-s -w" -o /prompt-sync .
+
+# Runtime stage: distroless has no shell, so the binary does its own
+# healthcheck (see -healthcheck in main.go). Runs as non-root.
+FROM gcr.io/distroless/static-debian12:nonroot
+
+COPY --from=build /prompt-sync /prompt-sync
+
+ENV PROMPT_SYNC_ADDR=:8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD ["/prompt-sync", "-healthcheck"]
+
+ENTRYPOINT ["/prompt-sync"]

Server/README.md

@@ -0,0 +1,116 @@
+# Prompt sync server
+
+Small Go service that stores one JSON blob per sync group, keyed by an 8-digit
+code (`1234-5678`). There is no authentication: the code is the shared secret,
+so anyone who knows it can read and overwrite that group. It is meant to be
+self-hosted for personal use, not exposed as a public service.
+
+## Requirements
+
+- Postgres (any recent version; developed against 18)
+- A host both Macs can reach — a VPS, a home server, or a Tailscale node
+
+## Run it
+
+```bash
+createdb prompt_sync
+cd Server
+PROMPT_SYNC_DATABASE_URL="postgres://localhost:5432/prompt_sync?sslmode=disable" \
+  go run .            # or: go build -o prompt-sync . && ./prompt-sync
+```
+
+| Env var | Default |
+| --- | --- |
+| `PROMPT_SYNC_ADDR` | `:8080` |
+| `PROMPT_SYNC_DATABASE_URL` | `postgres://localhost:5432/prompt_sync?sslmode=disable` |
+
+The schema is created on startup. Every request is logged as
+`METHOD PATH STATUS DURATION`; SIGTERM/SIGINT shut down gracefully so an
+in-flight push is not cut off mid-write. If the database is not reachable yet
+it retries five times, 2s apart, before giving up.
+
+> **`sslmode` matters.** lib/pq defaults to `sslmode=require`, so a connection
+> string copied from a host that runs Postgres *without* TLS (Coolify's
+> internal Postgres, a plain `docker run postgres`, Homebrew) fails with
+> `pq: SSL is not enabled on the server`. Append `?sslmode=disable` in that
+> case — the server prints exactly that hint when it hits this.
+
+## Deploying with Coolify
+
+Use a Dockerfile application pointed at this repo with base directory `Server/`
+(so Coolify builds `Server/Dockerfile`), expose port `8080`, and set:
+
+| Variable | Value |
+| --- | --- |
+| `PROMPT_SYNC_DATABASE_URL` | your Postgres URL **plus `?sslmode=disable`** |
+| `PROMPT_SYNC_ADDR` | `:8080` (this is already the default) |
+
+Coolify detects the `HEALTHCHECK` in the Dockerfile and runs
+`prompt-sync -healthcheck` with its 5s start period, so the container only goes
+live once `/healthz` answers. It also logs a generic warning that a healthcheck
+needs `curl` or `wget` — that does not apply here, the binary does its own
+check, so there is no reason to add either to the image (it is distroless and
+has no shell).
+
+## Run with Docker
+
+The image is a static binary on `distroless` (non-root, no shell), so its
+`HEALTHCHECK` calls `prompt-sync -healthcheck`, which pings the local
+`/healthz` — no curl needed in the image. That is what `docker ps` reports as
+the container health.
+
+```bash
+docker build -t prompt-sync Server/
+docker run -d --name prompt-sync -p 8080:8080 \
+  -e PROMPT_SYNC_DATABASE_URL="postgres://user:pass@host:5432/prompt_sync?sslmode=disable" \
+  prompt-sync
+
+docker logs -f prompt-sync         # request log
+```
+
+Postgres stays outside the container; the server only needs a URL. If Postgres
+runs on the Docker host itself, `host` is `host.docker.internal` on macOS and
+Windows, or the host's LAN address on Linux (`--network host` also works).
+
+## Deploy to a host
+
+Build for the host's architecture and ship the image, or build it on the host
+itself (a `git clone` plus `docker build` is usually simplest):
+
+```bash
+# build on the Mac for a linux/arm64 host, then copy it over
+docker build --platform linux/arm64 -t prompt-sync Server/
+docker save prompt-sync | gzip > prompt-sync.tar.gz
+scp prompt-sync.tar.gz <host>:
+ssh <host> 'gunzip -c prompt-sync.tar.gz | docker load'
+
+ssh <host> 'docker run -d --name prompt-sync --restart unless-stopped \
+  -p 8080:8080 \
+  -e PROMPT_SYNC_DATABASE_URL="postgres://user:pass@db-host:5432/prompt_sync?sslmode=disable" \
+  prompt-sync'
+```
+
+Put it behind TLS if it is reachable from the internet — the code is the only
+secret, and it travels in the URL path. Both plain HTTP and HTTPS work from the
+app; an HTTP URL is often fine over a LAN or Tailscale.
+
+## Endpoints
+
+| Method | Path | Behaviour |
+| --- | --- | --- |
+| `POST` | `/api/codes` | Generates a unique code, inserts an empty group |
+| `GET` | `/api/sync/{code}` | `{"version":N,"updatedAt":…,"data":{…}\|null}`, 404 if unknown |
+| `GET` | `/api/sync/{code}/version` | `{"version":N}` — cheap poll used by the app |
+| `PUT` | `/api/sync/{code}` | Upserts the payload, returns the incremented version |
+| `GET` | `/healthz` | Liveness (200) |
+
+Payloads are opaque `JSONB`; the server never parses note contents. Bodies are
+capped at 50 MB, which is generous enough for base64 photos.
+
+## Backups
+
+The whole state is one table, so `pg_dump prompt_sync` is a complete backup:
+
+```bash
+pg_dump prompt_sync | gzip > prompt_sync-$(date +%F).sql.gz
+```

Server/main.go

@@ -6,6 +6,7 @@
 //
 //	POST /api/codes           -> {"code":"1234-5678"}        (create group)
 //	GET  /api/sync/{code}     -> {"version":N,"data":{...}}  (404 if unknown)
+//	GET  /api/sync/{code}/version -> {"version":N}           (cheap poll)
 //	PUT  /api/sync/{code}     -> {"version":N+1}             (upsert payload)
 //	GET  /healthz             -> 200
 //
@@ -16,6 +17,7 @@
 package main
 
 import (
+	"context"
 	"crypto/rand"
 	"database/sql"
 	"encoding/json"
@@ -23,7 +25,10 @@ import (
 	"log"
 	"net/http"
 	"os"
+	"os/signal"
 	"regexp"
+	"strings"
+	"syscall"
 	"time"
 
 	_ "github.com/lib/pq"
@@ -44,6 +49,13 @@ type Server struct {
 }
 
 func main() {
+	// -healthcheck pings the local /healthz and exits non-zero on failure. It
+	// exists so the container image can run on a shell-less base (distroless),
+	// where there is no wget or curl for a HEALTHCHECK to use.
+	if len(os.Args) > 1 && os.Args[1] == "-healthcheck" {
+		os.Exit(healthcheck())
+	}
+
 	dsn := os.Getenv("PROMPT_SYNC_DATABASE_URL")
 	if dsn == "" {
 		dsn = "postgres://localhost:5432/prompt_sync?sslmode=disable"
@@ -53,14 +65,11 @@ func main() {
 		addr = ":8080"
 	}
 
-	db, err := sql.Open("postgres", dsn)
+	db, err := openDatabase(dsn)
 	if err != nil {
-		log.Fatalf("open database: %v", err)
+		log.Fatalf("connect to database: %v%s", err, hintFor(err))
 	}
 	defer db.Close()
-	if err := db.Ping(); err != nil {
-		log.Fatalf("connect to database: %v", err)
-	}
 	if _, err := db.Exec(schema); err != nil {
 		log.Fatalf("ensure schema: %v", err)
 	}
@@ -69,13 +78,112 @@ func main() {
 	mux := http.NewServeMux()
 	mux.HandleFunc("POST /api/codes", s.createCode)
 	mux.HandleFunc("GET /api/sync/{code}", s.getSync)
+	mux.HandleFunc("GET /api/sync/{code}/version", s.getVersion)
 	mux.HandleFunc("PUT /api/sync/{code}", s.putSync)
 	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusOK)
 	})
 
+	server := &http.Server{
+		Addr:              addr,
+		Handler:           withLogging(mux),
+		ReadHeaderTimeout: 10 * time.Second,
+	}
+
+	// Shut down cleanly so a redeploy (systemd restart, container stop) never
+	// cuts off an in-flight push and leaves a client thinking it failed.
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+	go func() {
+		<-stop
+		log.Println("shutting down")
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		_ = server.Shutdown(ctx)
+	}()
+
 	log.Printf("prompt-sync listening on %s", addr)
-	log.Fatal(http.ListenAndServe(addr, mux))
+	if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+		log.Fatalf("serve: %v", err)
+	}
+}
+
+// openDatabase connects, retrying briefly so a deploy is not marked unhealthy
+// just because Postgres was still starting up.
+func openDatabase(dsn string) (*sql.DB, error) {
+	db, err := sql.Open("postgres", dsn)
+	if err != nil {
+		return nil, err
+	}
+	var lastErr error
+	for attempt := 1; attempt <= 5; attempt++ {
+		if lastErr = db.Ping(); lastErr == nil {
+			return db, nil
+		}
+		if attempt < 5 {
+			log.Printf("database not ready (attempt %d/5): %v", attempt, lastErr)
+			time.Sleep(2 * time.Second)
+		}
+	}
+	db.Close()
+	return nil, lastErr
+}
+
+// hintFor turns the most common connection failure into something actionable.
+// lib/pq defaults to sslmode=require, so any DSN copied from a host that runs
+// Postgres without TLS (Coolify's internal Postgres, docker-compose, Homebrew)
+// fails with a bare "SSL is not enabled on the server".
+func hintFor(err error) string {
+	if !strings.Contains(err.Error(), "SSL is not enabled") {
+		return ""
+	}
+	return "\n\nhint: lib/pq defaults to sslmode=require, but that Postgres has TLS off." +
+		"\n      Append ?sslmode=disable to PROMPT_SYNC_DATABASE_URL" +
+		"\n      (e.g. postgres://user:pass@host:5432/prompt_sync?sslmode=disable)."
+}
+
+// healthcheck returns 0 when the local /healthz answers 200.
+func healthcheck() int {
+	addr := os.Getenv("PROMPT_SYNC_ADDR")
+	if addr == "" {
+		addr = ":8080"
+	}
+	if strings.HasPrefix(addr, ":") {
+		addr = "127.0.0.1" + addr
+	}
+	client := &http.Client{Timeout: 3 * time.Second}
+	response, err := client.Get("http://" + addr + "/healthz")
+	if err != nil {
+		log.Printf("healthcheck: %v", err)
+		return 1
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		log.Printf("healthcheck: unexpected status %d", response.StatusCode)
+		return 1
+	}
+	return 0
+}
+
+// withLogging keeps a one-line trail of method, path, status and duration so a
+// self-hosted deployment can be debugged from journalctl or docker logs.
+func withLogging(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		started := time.Now()
+		recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+		next.ServeHTTP(recorder, r)
+		log.Printf("%s %s %d %s", r.Method, r.URL.Path, recorder.status, time.Since(started).Round(time.Millisecond))
+	})
+}
+
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (r *statusRecorder) WriteHeader(status int) {
+	r.status = status
+	r.ResponseWriter.WriteHeader(status)
 }
 
 // createCode generates a unique 8-digit code, formats it as 1234-5678, and
@@ -136,6 +244,27 @@ func (s *Server) getSync(w http.ResponseWriter, r *http.Request) {
 		version, updatedAt.UTC().Format(time.RFC3339), data)
 }
 
+// getVersion is the cheap poll: clients ask for the version every few seconds
+// and only download the payload (which can carry base64 images) when it moved.
+func (s *Server) getVersion(w http.ResponseWriter, r *http.Request) {
+	code := r.PathValue("code")
+	if !codePattern.MatchString(code) {
+		writeError(w, http.StatusBadRequest, "code must look like 1234-5678")
+		return
+	}
+	var version int64
+	err := s.db.QueryRow(`SELECT version FROM sync_groups WHERE code = $1`, code).Scan(&version)
+	if err == sql.ErrNoRows {
+		writeError(w, http.StatusNotFound, "unknown code")
+		return
+	}
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "database error")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]int64{"version": version})
+}
+
 func (s *Server) putSync(w http.ResponseWriter, r *http.Request) {
 	code := r.PathValue("code")
 	if !codePattern.MatchString(code) {

Sources/Prompt/SyncService.swift

@@ -39,6 +39,9 @@ final class SyncService: ObservableObject {
     private static let urlKey = "sync.serverURL"
     private static let versionKey = "sync.version"
 
+    /// Where sync points unless the user overrides it in the sync panel.
+    static let defaultServerURL = "https://prompt.tzgyn.dev"
+
     private var lastVersion: Int64 {
         get { Int64(defaults.integer(forKey: Self.versionKey)) }
         set { defaults.set(newValue, forKey: Self.versionKey) }
@@ -54,7 +57,7 @@ final class SyncService: ObservableObject {
 
     private init() {
         code = defaults.string(forKey: Self.codeKey)
-        serverURL = defaults.string(forKey: Self.urlKey) ?? "http://localhost:8080"
+        serverURL = defaults.string(forKey: Self.urlKey) ?? Self.defaultServerURL
     }
 
     func start() {
@@ -181,22 +184,34 @@ final class SyncService: ObservableObject {
     }
 
     private func poll() {
-        guard !isSyncing, let code, let url = endpoint("/api/sync/\(code)") else { return }
+        guard !isSyncing, let code, let versionURL = endpoint("/api/sync/\(code)/version") else { return }
         Task {
             do {
-                let (data, response) = try await URLSession.shared.data(from: url)
-                if (response as? HTTPURLResponse)?.statusCode == 404 {
+                // Cheap poll first: the full payload can be megabytes of
+                // base64 images, so only download it when the version moved.
+                let (versionData, versionResponse) = try await URLSession.shared.data(from: versionURL)
+                if (versionResponse as? HTTPURLResponse)?.statusCode == 404 {
                     lastError = "Sync group no longer exists on the server"
                     return
                 }
-                guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
-                    syncLog("poll HTTP \((response as? HTTPURLResponse)?.statusCode ?? -1)")
+                guard let versionHTTP = versionResponse as? HTTPURLResponse, versionHTTP.statusCode == 200 else {
+                    syncLog("poll HTTP \((versionResponse as? HTTPURLResponse)?.statusCode ?? -1)")
                     return
                 }
+                let remoteVersion = try JSONDecoder().decode([String: Int64].self, from: versionData)["version"] ?? 0
+                guard remoteVersion > lastVersion else {
+                    lastError = nil
+                    return
+                }
+                syncLog("poll remote v\(remoteVersion) local v\(lastVersion) — fetching payload")
+                guard let payloadURL = endpoint("/api/sync/\(code)") else { return }
+                let (data, response) = try await URLSession.shared.data(from: payloadURL)
+                guard let http = response as? HTTPURLResponse, http.statusCode == 200 else { return }
                 let remote = try JSONDecoder().decode(SyncGetResponse.self, from: data)
-                syncLog("poll remote v\(remote.version) local v\(lastVersion)")
-                if remote.version > lastVersion, let payload = remote.data {
+                if let payload = remote.data {
                     apply(payload, version: remote.version)
+                } else {
+                    lastVersion = remote.version
                 }
                 lastError = nil
             } catch {