Backend quick start

1. Environment

cp .env.example .env
# edit .env to set DATABASE_URL, JWT_SECRET, AUTH_REFRESH_PEPPER, OPENAI_API_KEY, etc.

The .env file is consumed both by Docker Compose (for variable substitution) and by the containers themselves (env_file). Never commit your personal .env—the file is ignored by git.

Apple subscriptions use:

• APPLE_MONTHLY_PRODUCT_ID, APPLE_YEARLY_PRODUCT_ID
• APPLE_ISSUER_ID, APPLE_KEY_ID, APPLE_BUNDLE_ID
• APPLE_PRIVATE_KEY_PATH
• APPLE_SERVER_ENVIRONMENT (production, sandbox, or auto)
  • auto tries production first, then sandbox (recommended for one backend that serves both App Store live and TestFlight/review flows)

If Apple Server API credentials are not set, the backend still accepts ASN/confirm and uses local history for sync.

Optional overrides for Compose can be kept in docker-compose.local.yml (ignored). Start the stack with both files:

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build

2. Run with Docker

docker compose up --build

The API becomes available at http://127.0.0.1:8080. Compose boots Postgres, applies migrations via Atlas and starts the server at cmd/server.

For local product testing with seeded content and access backfill:

make dev-up

This target runs compose-up, seed-local, and backfill-local.

3. Run without Docker

Ensure Postgres is running and reachable via DATABASE_URL, then:

go run ./cmd/server

4. Migrations

• Create a migration: make migrate-new name=add_table
• Hash migrations (Atlas checkpoint): make migrate-hash
• Apply migrations outside Compose: atlas migrate apply --dir file://migration --url "$DATABASE_URL"

5. Testing

• Unit tests: make test
• Integration tests (requires Docker/Testcontainers): make integration-test

6. Local data helpers

• Seed local data: make seed-local
• Apply access backfill on current local DB: make backfill-local
• Full local startup + seed + backfill: make dev-up

Set OPENAI_API_KEY in your environment when you want to exercise chat-related flows locally.