From 806bd07f802f77287bdbd7f8cae89900f3c14a1e Mon Sep 17 00:00:00 2001
From: treyt <treyt@treyts-Mac-mini.localdomain>
Date: Tue, 24 Feb 2026 21:29:52 -0600
Subject: [PATCH] Update README for split dev/prod Docker config

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 49 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 21e4ee7..b1bdeef 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ Go REST API for the Casera (MyCrib) property management platform. Powers iOS and
 
 ### Option A: Docker (Recommended)
 
-This starts PostgreSQL, Redis, the API server, background worker, and admin panel in containers.
+This starts PostgreSQL, Redis, the API server, background worker, and admin panel in containers using the self-contained dev compose file.
 
 ```bash
 # 1. Clone the repo
@@ -37,8 +37,8 @@ cd myCribAPI-go
 cp .env.example .env
 # Edit .env — at minimum set SECRET_KEY to a random 32+ char string
 
-# 3. Start all services
-make docker-up
+# 3. Build and start all services
+make docker-dev
 
 # 4. Seed the database with lookup data (required)
 docker exec -i casera-db psql -U casera -d casera < seeds/001_lookups.sql
@@ -66,7 +66,7 @@ cd myCribAPI-go
 make deps
 
 # 3. Start PostgreSQL and Redis via Docker
-docker compose up -d db redis
+docker compose -f docker-compose.dev.yml up -d db redis
 
 # 4. Create your environment file
 cp .env.example .env
@@ -165,8 +165,8 @@ myCribAPI-go/
 ├── seeds/                       # Seed data (lookups, test users)
 ├── templates/emails/            # Email templates
 ├── docs/                        # API docs, OpenAPI spec
-├── docker-compose.yml           # Production-like Docker setup
-├── docker-compose.dev.yml       # Development overrides
+├── docker-compose.yml           # Production / Docker Swarm config
+├── docker-compose.dev.yml       # Self-contained local dev config
 ├── Dockerfile                   # Multi-stage build (api, worker, admin)
 ├── Makefile                     # Build, test, Docker commands
 └── .env.example                 # Environment variable template
@@ -181,7 +181,7 @@ make run              # Run API server
 make run-worker       # Run background worker
 make deps             # Install/tidy Go dependencies
 make build            # Build API binary
-make build-all        # Build API + worker + admin binaries
+make build-all        # Build API + worker binaries
 make fmt              # Format code
 make vet              # Vet code
 make lint             # Run golangci-lint
@@ -202,12 +202,20 @@ go test -run TestTaskHandler_CreateTask ./internal/handlers
 
 ### Docker
 
+Two compose files:
+- **`docker-compose.dev.yml`** — self-contained local dev (build from source, `container_name`, `depends_on`, dev defaults)
+- **`docker-compose.yml`** — production / Docker Swarm (image refs, `deploy:` sections, overlay network)
+
 ```bash
-make docker-up        # Start all containers
-make docker-down      # Stop all containers
-make docker-logs      # Tail container logs
-make docker-restart   # Restart all containers
-make docker-dev       # Start in dev mode (source mounted, debug on)
+# Dev
+make docker-dev       # Build and start all dev containers (foreground)
+make docker-up        # Start dev containers (detached)
+make docker-down      # Stop dev containers
+make docker-logs      # Tail dev container logs
+make docker-restart   # Restart dev containers
+
+# Prod
+make docker-build-prod  # Build production images (api, worker, admin)
 ```
 
 ### Database Migrations
@@ -249,7 +257,9 @@ All test users have password: `password123`
 
 All protected endpoints require an `Authorization: Token <token>` header.
 
-## Production Deployment (Dokku)
+## Production Deployment
+
+### Dokku
 
 ```bash
 # Push to Dokku
@@ -262,6 +272,19 @@ cat seeds/001_lookups.sql | dokku postgres:connect casera-db
 dokku logs casera-api -t
 ```
 
+### Docker Swarm
+
+```bash
+# Build and push production images
+make docker-build-prod
+docker push ${REGISTRY}/casera-api:${TAG}
+docker push ${REGISTRY}/casera-worker:${TAG}
+docker push ${REGISTRY}/casera-admin:${TAG}
+
+# Deploy the stack (all env vars must be set in .env or environment)
+docker stack deploy -c docker-compose.yml casera
+```
+
 ## Related Projects
 
 - **Mobile App (KMM)**: `../MyCribKMM` — Kotlin Multiplatform iOS/Android client