go-service-bootstrap

When to Use

• Setting up main.go to wire all dependencies
• Adding environment-based configuration
• Managing secrets (DB passwords, API keys)
• Deciding what changes between local/dev/staging/prod
• Adding a new adapter/implementation swap
• Setting up docker-compose profiles

---

Critical Patterns

Pattern	Rule
Manual DI	No DI frameworks (no Wire, no Dig) — Go's simplicity is the feature
Constructor injection	All dependencies via NewXxx(deps...) constructors
Config from environment	All configuration from env vars, no config files in production
Secrets via env	Secrets injected via environment, never hardcoded or in repo
Wire in main.go	cmd/server/main.go is the ONLY place that knows all concrete types
Same code, different config	Never if env == "production" in domain — only in config and infra

---

Environments

Environment	APP_ENV	Purpose
local	local	Developer machine, docker-compose, fast feedback
dev	development	Shared cloud environment for team integration
staging	staging	Pre-production replica, QA and smoke tests
production	production	Live, real users, real money

What Changes Per Environment

Logging

Setting	local	dev	staging	production
Format	text	JSON	JSON	JSON
Level	debug	debug	info	info
Source location	yes	yes	no	no

Database

Setting	local (no Docker)	local (Docker)	dev	staging	production
Provider	memory	postgres	postgres	postgres	postgres
Host	N/A	localhost	Cloud SQL / RDS	Cloud SQL / RDS	Cloud SQL / RDS
SSL	N/A	disable	require	require	verify-full
Max connections	N/A	5	10	20	25
Password source	N/A	.env file	Secret manager	Secret manager	Secret manager

The in-memory provider uses a pure Go map-based repository — zero external dependencies. See go-repository-pattern skill for implementation details.

Observability

Setting	local	dev	staging	production
Tracing	disabled or Jaeger local	OTel Collector → Jaeger	OTel Collector → Jaeger + S3	OTel Collector → Jaeger + S3
Trace sampling	100%	100%	50%	10%
Metrics	disabled	Prometheus	Prometheus	Prometheus + S3 export

Messaging

Setting	local	dev	staging	production
Provider	NATS (docker-compose)	NATS cluster	NATS cluster	NATS cluster
URL	nats://localhost:4222	Cloud endpoint	Cloud endpoint	Cloud endpoint

Object Storage

Setting	local	dev	staging	production
Provider	MinIO (docker-compose)	S3 / GCS	S3 / GCS	S3 / GCS
Endpoint	http://localhost:9000	(default SDK)	(default SDK)	(default SDK)
Force path style	true	false	false	false

Security

Setting	local	dev	staging	production
CORS origins	*	*.bastet.dev	*.bastet.dev	bastet.cl
Rate limiting	disabled	soft limits	production limits	production limits
JWT validation	mock / disabled	real	real	real
Swagger UI	enabled	enabled	enabled	disabled

---

Configuration

See assets/config.go — centralized config struct with typed helpers.

All configuration loaded once via config.Load(). Typed helpers: getEnv, requireEnv, getEnvInt, getEnvBool, getEnvDuration.

---

main.go — The Composition Root

See assets/main.go

The composition root follows a numbered sequence:

1. Load config
2. Setup logger
3. Infrastructure — databases
4. Infrastructure — messaging
5. Infrastructure — storage
6. Repositories (adapters)
7. Application services (use cases)
8. HTTP handlers
9. Router
10. Start server

---

Logger Setup

See assets/logger.go — environment-aware slog configuration (text for local, JSON for others).

---

Health Check Convention

Every service exposes two endpoints:

Endpoint	Purpose	When it fails
GET /health	Liveness — is the process alive?	Restart the container
GET /ready	Readiness — can it serve traffic?	Stop sending traffic

See assets/health_check.go

---

Graceful Shutdown

See assets/server.go — listens for context cancellation, 10-second shutdown timeout.

---

Environment Variable Files

api/{service}/
  .env.example        # Committed — all keys, safe defaults for local
  .env                 # NOT committed — developer's local overrides

See assets/env.example

NEVER commit .env — only .env.example.

Secrets (dev/staging/prod)

Secrets are NEVER in env files for non-local environments. Use:

Provider	Tool
GCP	Google Secret Manager
AWS	AWS Secrets Manager / SSM Parameter Store
Kubernetes	Sealed Secrets / External Secrets Operator

Secrets are injected as environment variables at runtime by the orchestrator.

---

Docker-Compose Profiles

See assets/docker-compose.example.yml

# Start everything
docker-compose --profile local up -d

# Start only infra (DB, NATS, MinIO) — run services natively
docker-compose --profile infra up -d

# Start only observability stack
docker-compose --profile observability up -d

---

Assets

File	Description
assets/config.go	Centralized config struct with typed env helpers
assets/main.go	Composition root with numbered wiring sequence
assets/logger.go	Environment-aware slog setup
assets/server.go	Graceful HTTP server with shutdown
assets/health_check.go	Liveness and readiness endpoints
assets/env.example	Environment variable template for local dev
assets/docker-compose.example.yml	Docker-compose with profiles for local dev

---

Commands

# Local dev with .env
cp .env.example .env
docker-compose --profile infra up -d
go run ./cmd/server

# Or use direnv
echo 'dotenv' > .envrc && direnv allow

# Run with specific env
APP_ENV=development go run ./cmd/server

# Verify environment
curl http://localhost:8080/health

---

Anti-Patterns

Don't	Do
DI frameworks (Wire, Dig, fx)	Manual constructor injection in main.go
Global variables for DB/config	Pass dependencies through constructors
Config files (YAML/TOML) in production	Environment variables only
Secrets in repo or config files	Inject via env vars, use secret manager in CI/CD
Init functions with side effects	Explicit initialization in main.go
Scattered os.Getenv calls	Centralized config.Load()
if env == "production" in domain	Environment logic in config and infrastructure only
Different code paths per environment	Same code, different configuration
Skip SSL in staging	Staging mirrors production security
Disable rate limiting in staging	Staging mirrors production limits
Hardcode environment values	Always read from os.Getenv via config.Load()