docs: add local orbstack setup

AGENTS.md

@@ -47,6 +47,7 @@ go vet ./...
 - `internal/handlers/wallet_auth.go`: wallet nonce, signature verification, wallet profile.
 - `internal/handlers/upload.go`: admin multipart upload to local disk or S3.
 - `migrations/`: SQL schema files; there is no Go migration runner yet.
+- `compose.yaml`: local OrbStack/Docker Compose setup with PostgreSQL + API.
 
 ## Important implementation patterns
 
@@ -68,6 +69,7 @@ go vet ./...
 
 ## Deployment/runtime notes
 
+- `compose.yaml` runs local development in OrbStack/Docker: PostgreSQL on host port `5433`, API on host port `8080`.
 - Dockerfile builds a static Go binary in a `golang:1.24-alpine` builder and runs it on Alpine.
 - `UPLOAD_DIR` defaults to `./uploads`; Docker sets it to `/app/uploads`.
 - When `S3_BUCKET` is set and AWS config loads, uploads go to S3. Otherwise uploads stay local.

README.md

@@ -4,6 +4,8 @@ Go backend for the ARK Library / ARK Database website.
 
 If Go is new for you: start with **[docs/GO_FOR_BEGINNERS.md](docs/GO_FOR_BEGINNERS.md)**, then read **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
 
+For local Docker/OrbStack development, see **[docs/LOCAL_ORBSTACK.md](docs/LOCAL_ORBSTACK.md)**.
+
 ## What this service does
 
 - Serves public library data under `/api`.
@@ -38,7 +40,24 @@ static/                     # bundled static assets copied into uploads
 
 ## Quick local run
 
-### 1) Start PostgreSQL
+### Option A: OrbStack / Docker Compose
+
+```bash
+cd Arkie-Library-Backend
+docker compose up --build
+```
+
+Then check:
+
+```bash
+curl http://localhost:8080/healthz
+```
+
+See **[docs/LOCAL_ORBSTACK.md](docs/LOCAL_ORBSTACK.md)** for details.
+
+### Option B: Manual PostgreSQL + Go
+
+#### 1) Start PostgreSQL
 
 Example with Docker:
 
@@ -51,7 +70,7 @@ docker run --name ark-postgres \
   -d postgres:16
 ```
 
-### 2) Apply schema once
+#### 2) Apply schema once
 
 `migrations/001_init.sql` is for a fresh empty database. Do not run it twice on the same DB unless you reset the DB first.
 
@@ -68,7 +87,7 @@ psql "$DATABASE_URL" -f migrations/002_wallet_auth.sql
 export RUN_WALLET_AUTH_SCHEMA=false
 ```
 
-### 3) Configure env
+#### 3) Configure env
 
 Copy the example and edit values as needed:
 
@@ -78,7 +97,7 @@ cp .env.example .env
 
 This project does not auto-load `.env`; either export variables in your shell or run with a dotenv helper.
 
-### 4) Run the server
+#### 4) Run the server
 
 ```bash
 go run ./cmd/server

compose.yaml

@@ -0,0 +1,45 @@
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: arkie-library-db
+    environment:
+      POSTGRES_USER: ark
+      POSTGRES_PASSWORD: ark
+      POSTGRES_DB: arkdb
+    ports:
+      # Host port 5433 avoids conflicts with any existing local PostgreSQL on 5432.
+      - "5433:5432"
+    volumes:
+      - arkie_postgres_data:/var/lib/postgresql/data
+      - ./migrations/001_init.sql:/docker-entrypoint-initdb.d/001_init.sql:ro
+      - ./migrations/002_wallet_auth.sql:/docker-entrypoint-initdb.d/002_wallet_auth.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ark -d arkdb"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  api:
+    build: .
+    container_name: arkie-library-api
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      HTTP_ADDR: ":8080"
+      DATABASE_URL: "postgres://ark:ark@db:5432/arkdb?sslmode=disable"
+      JWT_SECRET: "local-dev-change-me"
+      CORS_ORIGINS: "${CORS_ORIGINS:-http://localhost:5173,http://localhost:3000}"
+      UPLOAD_DIR: "/app/uploads"
+      SEED_ADMIN: "${SEED_ADMIN:-true}"
+      ADMIN_EMAIL: "${ADMIN_EMAIL:-admin@ark.local}"
+      ADMIN_PASSWORD: "${ADMIN_PASSWORD:-admin123}"
+      RUN_WALLET_AUTH_SCHEMA: "true"
+    ports:
+      - "8080:8080"
+    volumes:
+      - arkie_uploads:/app/uploads
+
+volumes:
+  arkie_postgres_data:
+  arkie_uploads:

docs/LOCAL_ORBSTACK.md

@@ -0,0 +1,102 @@
+# Local Development with OrbStack
+
+Yes — this backend can run locally in OrbStack.
+
+This repo includes `compose.yaml` with:
+
+- `db`: PostgreSQL 16
+- `api`: the Go backend built from the local `Dockerfile`
+
+## Quick start
+
+From `Arkie-Library-Backend`:
+
+```bash
+docker compose up --build
+```
+
+Then test:
+
+```bash
+curl http://localhost:8080/healthz
+```
+
+Expected output:
+
+```text
+ok
+```
+
+## Local URLs
+
+| Service | URL |
+| --- | --- |
+| Backend API | `http://localhost:8080` |
+| Health check | `http://localhost:8080/healthz` |
+| PostgreSQL from Mac host | `localhost:5433` |
+| PostgreSQL from API container | `db:5432` |
+
+The DB host port is `5433` to avoid conflicts with any local PostgreSQL already using `5432`.
+
+## Default local admin
+
+When the DB is empty, compose seeds an admin because `SEED_ADMIN=true` by default:
+
+```text
+email: admin@ark.local
+password: admin123
+```
+
+Override if needed:
+
+```bash
+ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='your-password' docker compose up --build
+```
+
+## Frontend connecting to local backend
+
+In `Arkie-Library-Frontend`, use:
+
+```bash
+VITE_API_URL=http://localhost:8080
+```
+
+Then run your frontend dev server normally.
+
+## Running Go locally but DB in OrbStack
+
+For faster backend development, you can run only PostgreSQL in OrbStack and run Go directly on your Mac.
+
+Start DB only:
+
+```bash
+docker compose up db
+```
+
+In another terminal:
+
+```bash
+export DATABASE_URL='postgres://ark:ark@localhost:5433/arkdb?sslmode=disable'
+export HTTP_ADDR=':8080'
+export JWT_SECRET='local-dev-change-me'
+export CORS_ORIGINS='http://localhost:5173,http://localhost:3000'
+export SEED_ADMIN=true
+
+go run ./cmd/server
+```
+
+## Reset local database
+
+This deletes local development data and reruns migrations on next start:
+
+```bash
+docker compose down -v
+docker compose up --build
+```
+
+## Important notes
+
+- This is local-only and does not touch the production server.
+- `migrations/001_init.sql` runs only when the PostgreSQL volume is first created.
+- If you change migrations and want them reapplied, reset with `docker compose down -v`.
+- Do not use production `DATABASE_URL` for local development unless you intentionally want to modify production data.