cookiecutter-coldbrew

Powered by Cookiecutter, Cookiecutter Coldbrew is a template for jumpstarting production-ready Go gRPC microservices with the ColdBrew framework.

Features

• Complete gRPC service with HTTP/JSON gateway (grpc-gateway)
• Kubernetes health checks (liveness + readiness probes)
• Prometheus metrics, distributed tracing, structured logging
• Request validation via protovalidate annotations
• Swagger UI for interactive API documentation
• Multi-stage Docker build for minimal production images
• CI/CD pipelines for GitHub Actions and GitLab CI
• golangci-lint v2 configuration with govulncheck
• Makefile with build, test, lint, benchmark, and run targets
• Build-time version injection (git commit, branch, date)
• Local dev stack with 20 docker-compose profiles (databases, caches, brokers, AWS/GCP emulators)
• Grafana dashboard + Jaeger tracing pre-configured in obs profile
• Application metrics package (interface-based, mockable, promauto)
• gRPC load testing with ghz

Prerequisites

Install Cookiecutter:

brew install cookiecutter

Or via pip:

pip install cookiecutter

Usage

cookiecutter gh:go-coldbrew/cookiecutter-coldbrew

Answer the prompts:

source_path [github.com/ankurs]: github.com/yourname
name [MyApp]: EchoServer
grpc_package [com.github.ankurs]: com.github.yourname
service_name [MySvc]: EchoSvc
project_short_description [EchoServer is a Golang project.]:
goprivate []:
docker_image [alpine:latest]:
docker_build_image [golang]:
Select docker_build_image_version:
1 - 1.26
2 - 1.25
Choose from 1, 2 [1]: 1
include_docker_compose [y/n] (y):
local_services (postgres,mysql,...,adminer) [postgres,redis]:

Then build and run:

cd EchoServer/
make run

Your service starts on :9090 (gRPC) and :9091 (HTTP/Swagger).

For a full walkthrough, see the Getting Started guide.

CI/CD

The generated project includes ready-to-use CI pipelines for both platforms. Delete whichever you don't need.

GitHub Actions (.github/workflows/go.yml)

Runs on push to main/master and on pull requests. Four parallel jobs: build, test (race detector + coverage), benchmark, and lint (govulncheck + golangci-lint). Each job has concurrency control to cancel duplicate runs.

GitLab CI (.gitlab-ci.yml)

Three jobs in a single test stage: unit-test (with Cobertura coverage report), lint (golangci-lint + govulncheck), and benchmark. Go module caching is enabled.

Docker

Uses multi-stage builds: compiles a static Go binary in the builder stage, then copies it to a minimal Alpine image. Ports 9090 (gRPC) and 9091 (HTTP) are exposed.

make build-docker
make run-docker

Documentation

• Getting Started — Full walkthrough
• ColdBrew Documentation — Framework reference
• How-To Guides — Tracing, logging, metrics, and more