Deployment

API image

make build-api
make dev-up
go run ./tools/cli database migrate
make serve-api

The API Dockerfile compiles the Go workspace and runs the binary in a distroless nonroot image. make serve-api runs the existing image, loads .env, and uses host networking so localhost dependency URLs reach the services started by make dev-up. Supply DATABASE_URL, RABBITMQ_URL, and a valid JWT_SECRET in that file. Use the Compose broker credentials documented in getting started. Override the environment file with API_ENV_FILE=.env.container or the API listen port with API_PORT=8082. Host networking requires Linux or Docker Desktop with host networking enabled. make dev-api runs the API with Air on the host instead.

Apply database migrations explicitly through pcli; the production API does not expose database maintenance routes or automatically migrate on startup.

Startup verifies PostgreSQL and JWT configuration, then connects RabbitMQ. Failure prevents the listener from starting. The listener uses PORT, handles interrupt/termination signals, and allows five seconds for HTTP shutdown before releasing dependencies. /healthz reports that the server handles requests; it is not a continuous dependency-readiness probe.

The checked-in Compose configuration is for development and currently starts dependencies only. To run the API container, enable its commented service and replace the short JWT secret. Redis is provisioned but is not currently initialized by the server. Do not infer production high availability, backup scheduling, email delivery, or durable notification storage from the development configuration.

Documentation image

make build-docs
make serve-docs

Both serve targets run existing images; rebuild explicitly after changing source.

Build stages generate Go documentation and example downloads, compile Markdown to HTML, and copy artifacts into Caddy. No API, database, or broker is started during this build. Dependency downloads require network access during an uncached build. The runtime contains Caddy and static files, with /healthz used by the container healthcheck.

The home page links to /swagger, /scalar, and /docs. /docs redirects to /docs/; nested pages and assets are served beneath that prefix. Unknown paths return 404. /openapi.yaml serves the checked-in spec with Cache-Control: no-cache. Rebuild after documentation, code-comment, fixture, or OpenAPI changes.

For revision-specific Go source links:

docker build --build-arg DOCS_SOURCE_REF=main -t prescriptoo-api-docs -f api-docs/Dockerfile .

Scalar and Swagger browser bundles retain their existing pinned jsDelivr URLs. The VitePress site and search assets are served locally; interactive API viewers require browser internet access. Run go run ./services/openapi -spec api/openapi.yaml from the repository root to start the older Go-hosted Scalar viewer, which serves only the OpenAPI reference and is separate from the full site.