Configuration

Configuration is split between environment variables (loaded from .env in development) and typed Go helpers under config/. Understanding both avoids “works on my machine” surprises in staging.

Environment file workflow

Copy .env.example → .env.
Fill database and security values.
Never commit .env with real secrets — rely on CI/CD secret stores in production.

godotenv is typically invoked from database setup code; if you deploy with pure environment variables (Docker/Kubernetes), you can omit the file as long as variables are injected.

Core variables (database)

Key	Typical dev value	Notes
`DB_HOST`	`localhost`	Use service name in Docker Compose networks.
`DB_PORT`	`5432`
`DB_USER`	`postgres`	Least privilege user in production.
`DB_PASS`	strong password	Rotate on compromise.
`DB_NAME`	`gin_starter`	Must exist before `--migrate:run`.

Connection errors almost always show up as dial tcp or password authentication failed in the first stack trace line.

Security variables

Key	Purpose
`JWT_SECRET`	Symmetric key for signing access JWTs. Use a long random string; rotate with a key versioning strategy if you ever leak it.

If you add refresh token signing or encryption at rest later, introduce additional keys with clear names (REFRESH_PEPPER, etc.).

HTTP / runtime

Key	Purpose
`GOLANG_PORT`	Port Gin binds to.
`APP_ENV`	When `localhost`, binds `0.0.0.0` for LAN testing (see `cmd/main.go` / `run`).

Behind nginx or a cloud load balancer, you often bind 8080 internally and map 443 externally.

Email configuration

Auth flows for verification and password reset send mail through helpers in config/email.go and pkg/utils (exact layout may evolve). You will configure:

SMTP host, port, username, password.
From address and display name.

Until SMTP is valid, treat those flows as development only or mock the sender in tests.

Logging

config/logger.go configures GORM’s logger (slow query thresholds, colours in dev). Tune log noise before shipping to centralised logging — high‑volume query logs can become expensive.

Multiple environments

Pattern:

Environment	How config differs
Local	`.env` on disk, verbose SQL logs.
Staging	CI secrets, read‑only replicas optional.
Production	Secrets manager, stricter log levels, no `AutoMigrate` in request path.

The starter does not ship a full feature flag system — add one when you need safe rollouts.

Checklist before first deploy

JWT_SECRET rotated from template default
Database credentials are not superuser unless required
Migrations applied in pipeline before new binary serves traffic
SMTP or notification provider verified with a real send

Next: Database & migrations for schema change mechanics.