README
¶
Go Starter
Go Starter is a template for OpenAPI-first, PostgreSQL-backed Go HTTP services: clone it, give it your names once, and build your service on it.
Status: pre-release; no tagged version yet.
What you get
- Cobra and Viper commands (
serve,migrate,seed) with layered configuration validated before anything opens - Chi routing and ogen types generated from
api/openapi.yml - PostgreSQL through pgx/v5, sqlc and Goose, with serialized embedded migrations
- JWT bearer authentication with an example user module and login endpoint
- Health endpoints, Prometheus metrics, Zap logging and optional OpenTelemetry export
- Login rate limiting, per process; forwarding headers are trusted only from
rate-limit.trusted-proxies - Unit tests and Testcontainers PostgreSQL integration tests, a CI workflow, GoReleaser and a Podman image build
It is a starter, not a deployment to ship unchanged: choose your secrets, CORS origins, connection limits, TLS termination and monitoring first.
Initialize a new project
Run the initializer once in a clean clone. It rewrites the module path, names, environment prefix, image and OpenAPI metadata, then deletes itself:
make init \
module=example.com/acme/orders \
app-name='Acme Orders' \
binary=orders-api \
env-prefix=ORDERS \
image=registry.example.com/acme/orders-api \
description='Order processing API'
The description is optional. Review the diff, then run make check.
Five-minute quickstart
You need Git, Go 1.26.5, Make, and Podman with a Compose provider.
git clone https://github.com/rfizzle/go-starter.git
cd go-starter
make tools
make env
cp .env.example .env
make dev-run
dev-run starts PostgreSQL, applies the migrations, seeds the development user
from .env, and serves on port 8080. In another terminal:
curl --fail http://localhost:8080/api/v1/healthz/readiness
curl --fail-with-body \
--header 'Content-Type: application/json' \
--data '{"email":"admin@example.com","password":"<seed-password>"}' \
http://localhost:8080/api/v1/login
Stop it with Ctrl-C and make dev-down. Settings come from flags, then
GOSTARTER_* environment variables, then the file given with --config;
./bin/gostarter serve --help (after make build) lists them. The credentials
in compose.yaml and .env.example are for development only.
Documents
AGENTS.md has the commands, the layout and the rules for anyone
changing the code; the design and the guides are in docs/, starting at
docs/README.md. Deployment is in
docs/development/deployment.md.
CONTRIBUTING.md, SECURITY.md and
CHANGELOG.md cover contributing, vulnerability reports and
notable changes.
Go Starter is available under the MIT License.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd defines the Cobra command tree and the process-level concerns around it: configuration file and environment binding through Viper, logger construction, and the build metadata linked in at release time.
|
Package cmd defines the Cobra command tree and the process-level concerns around it: configuration file and environment binding through Viper, logger construction, and the build metadata linked in at release time. |
|
internal
|
|
|
api/v1
Code generated by ogen, DO NOT EDIT.
|
Code generated by ogen, DO NOT EDIT. |
|
app
Package app is the application's composition root.
|
Package app is the application's composition root. |
|
auth
Package auth provides token validation, token generation, and the request-context carrier for the authenticated subject.
|
Package auth provides token validation, token generation, and the request-context carrier for the authenticated subject. |
|
cli
Package cli holds the process-level lifecycle helpers shared by the Cobra commands in cmd.
|
Package cli holds the process-level lifecycle helpers shared by the Cobra commands in cmd. |
|
cli/seed
Package seed provides idempotent development database seeding for the starter.
|
Package seed provides idempotent development database seeding for the starter. |
|
controller
Package controller maps the generated OpenAPI transport in internal/api/v1 onto business behavior.
|
Package controller maps the generated OpenAPI transport in internal/api/v1 onto business behavior. |
|
domain
Package domain defines business data, persistence inputs, and business-facing errors.
|
Package domain defines business data, persistence inputs, and business-facing errors. |
|
modules/credential
Package credential verifies a plaintext password against a user's stored bcrypt hash.
|
Package credential verifies a plaintext password against a user's stored bcrypt hash. |
|
modules/user
Package user implements PostgreSQL persistence for the example user business module.
|
Package user implements PostgreSQL persistence for the example user business module. |
|
platform/config
Package config defines the application's decoded configuration and its command-scoped validation rules.
|
Package config defines the application's decoded configuration and its command-scoped validation rules. |
|
platform/database
Package database defines technical database lifecycle contracts shared by PostgreSQL infrastructure.
|
Package database defines technical database lifecycle contracts shared by PostgreSQL infrastructure. |
|
platform/database/postgres
Package postgres provides PostgreSQL connection, migration, and metrics infrastructure.
|
Package postgres provides PostgreSQL connection, migration, and metrics infrastructure. |
|
platform/health
Package health evaluates the technical dependencies required for the application to serve traffic.
|
Package health evaluates the technical dependencies required for the application to serve traffic. |
|
platform/http/middleware
Package middleware provides the HTTP middleware the application's server mounts: structured request logging, panic recovery, request-body size limits, reserved-path-aware static file serving, and trusted-proxy-aware login rate limiting.
|
Package middleware provides the HTTP middleware the application's server mounts: structured request logging, panic recovery, request-body size limits, reserved-path-aware static file serving, and trusted-proxy-aware login rate limiting. |
|
platform/http/server
Package server implements the application's HTTP server: middleware stack, route mounting, and graceful lifecycle management.
|
Package server implements the application's HTTP server: middleware stack, route mounting, and graceful lifecycle management. |
|
platform/observability
Package observability wires the application's OpenTelemetry signals to an OTLP/gRPC collector.
|
Package observability wires the application's OpenTelemetry signals to an OTLP/gRPC collector. |
|
platform/ratelimiter
Package ratelimiter provides a bounded, process-local fixed-window rate limiter.
|
Package ratelimiter provides a bounded, process-local fixed-window rate limiter. |
|
templateinit
Package templateinit safely replaces the template's project identity.
|
Package templateinit safely replaces the template's project identity. |
|
scripts
|
|
|
docscheck
command
Command docscheck keeps a repository's documentation and its code honest with each other.
|
Command docscheck keeps a repository's documentation and its code honest with each other. |
|
skillscheck
command
Command skillscheck keeps the shared skills a repository vendors identical to their source.
|
Command skillscheck keeps the shared skills a repository vendors identical to their source. |
|
tools
|
|
|
initialize
command
Command initialize replaces the Go Starter template identity.
|
Command initialize replaces the Go Starter template identity. |
|
Package web exposes the framework-neutral static assets embedded in the service binary.
|
Package web exposes the framework-neutral static assets embedded in the service binary. |
Click to show internal directories.
Click to hide internal directories.