Deployment

This page covers shipping the Go API built from the starter. The MDX documentation site you are reading now is a separate Next.js project — deploy it to Vercel/Netlify independently if you want a public handbook.

Build artefacts

Single binary

CGO_ENABLED=0 GOOS=linux go build -o api ./cmd/main.go

CGO_ENABLED=0 produces a static binary suitable for minimal containers. Adjust GOOS / GOARCH for your target platform matrix.

Run migrations in CI/CD

Always run migrations with the same version of migration code as the binary about to serve traffic:

./api --migrate:run

If a migration fails, stop the rollout — partial schema with new code is worse than delaying a release.

Docker

The starter typically ships:

• Dockerfile for the API image.
• docker-compose.yml for local multi-service stacks (e.g. nginx + postgres).

Production image tips

• Use multi-stage builds — compile in a builder stage, copy only the binary into a distroless or alpine runtime image.
• Do not bake .env secrets into layers — inject at runtime.
• Run as non-root where your orchestrator allows.

Environment promotion

Rotate JWT_SECRET if you ever suspect leakage — all outstanding access tokens become invalid clients must re-login.

Reverse proxy

Place nginx, Caddy, or a cloud load balancer in front of Gin for:

• TLS termination.
• gzip / brotli compression.
• request size limits.

Gin should listen on an internal port; the proxy handles 443.

Observability (recommended adds)

Not included by default:

• Structured logging (JSON) with request IDs.
• Metrics (/metrics for Prometheus).
• Tracing (OpenTelemetry exporters).

Add middleware near Gin creation so every route benefits.

Hosting the documentation (Next.js)

This site (go-gin-clean-starter-docs) builds with:

npm install
npm run build
npm start

For Vercel:

1. Create a new project from the docs Git repository.
2. Framework preset: Next.js.
3. No environment variables are strictly required for static generation of MDX here.

Set a custom domain and optional metadataBase in app/layout.tsx later for correct Open Graph URLs.

Rollback strategy

If a deploy misbehaves after migrations:

1. Roll back the application binary to the previous version if it remains compatible with the current schema.
2. If migrations were backward incompatible, you may need a forward fix migration instead of reversing schema.

Design migrations to be expand-contract when serving zero-downtime traffic.

Support matrix

Keep a small internal table of which starter version maps to which API version tag in Git — your mobile apps or SPAs may depend on subtle JSON differences.