Toolbox and building blocks for new Go projects, to get started quickly and right-footed!
Pick and choose whatever is useful to you! Don't feel the need to use everything, or even to follow this structure.
This template provides two entry points:
- CLI application (
cmd/cli/main.go) - Command-line tool using urfave/cli - HTTP server (
cmd/httpserver/main.go) - Web server with graceful shutdown, health checks, and metrics
Makefilewithlint,test,build,fmtand more- Linting with
gofmt,gofumpt,go vet,staticcheckandgolangci-lint - Logging setup using the slog logger (with debug and json logging options)
- GitHub Workflows for linting and testing, as well as releasing and publishing Docker images
- Webserver with graceful shutdown, health probes, and Prometheus metrics
- Postgres database with migrations
Build and run the HTTP server:
make build-httpserver
./build/httpserver --listen-addr 127.0.0.1:8080 --metrics-addr 127.0.0.1:8090Build and run the CLI:
make build-cli
./build/cli| Directory | Description |
|---|---|
cmd/cli/ |
CLI application entry point (urfave/cli) |
cmd/httpserver/ |
HTTP server entry point |
httpserver/ |
HTTP server implementation (chi router, graceful shutdown) |
database/ |
Postgres database layer using sqlx |
database/migrations/ |
Database migrations (run automatically on connection) |
metrics/ |
Prometheus metrics (VictoriaMetrics-based) |
common/ |
Shared utilities (structured logging) |
The server runs two HTTP servers: main API (default :8080) and metrics (default :8090).
| Endpoint | Port | Description |
|---|---|---|
/api |
8080 | Main API endpoint |
/livez |
8080 | Liveness probe for health checks |
/readyz |
8080 | Readiness probe for health checks |
/drain |
8080 | Enable drain mode (for graceful shutdown) |
/undrain |
8080 | Disable drain mode |
/debug/* |
8080 | pprof debug endpoints (when --pprof flag is set) |
/metrics |
8090 | Prometheus metrics |
| Flag | Default | Description |
|---|---|---|
--listen-addr |
127.0.0.1:8080 |
Address for API server |
--metrics-addr |
127.0.0.1:8090 |
Address for Prometheus metrics |
--log-json |
false |
Log in JSON format |
--log-debug |
false |
Enable debug logging |
--log-uid |
false |
Add UUID to all log messages |
--log-service |
your-project |
Service name in logs |
--pprof |
false |
Enable pprof debug endpoint |
--drain-seconds |
45 |
Seconds to wait in drain HTTP request |
make build-cli # Build CLI binary to ./build/cli
make build-httpserver # Build HTTP server binary to ./build/httpserver
make build # Build all binariesmake lint # Run all linters (gofmt, gofumpt, go vet, staticcheck, golangci-lint)
make test # Run all tests
make fmt # Format code (gofmt, gci, gofumpt, go mod tidy)
make lt # Run both lint and testgo install mvdan.cc/gofumpt@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go install go.uber.org/nilaway/cmd/nilaway@latest
go install github.com/daixiang0/gci@latestDatabase tests require a running Postgres instance and the RUN_DB_TESTS environment variable:
# Start the database
docker run -d --name postgres-test -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres
# Run the tests
RUN_DB_TESTS=1 make test
# Stop the database
docker rm -f postgres-test| Variable | Description |
|---|---|
RUN_DB_TESTS |
Set to 1 to run database integration tests |
DB_DONT_APPLY_SCHEMA |
Set to skip automatic migration on database connection |
- Flashbots Repository Template - Public project setup
- go-utils - Common Go utilities
- goperf.dev - Advanced Golang knowledge, tips & tricks