ColdBrew

A Kubernetes-native Go microservice framework for building production-grade gRPC services with built-in observability, resilience, and HTTP gateway support. Follows 12-factor principles out of the box.

Production-proven: Powers 100+ microservices, handling peaks of ~70k QPS per service at Gojek.

Get Started View Packages How To GitHub

What You Get Out of the Box

Quick Start

Generate a new service in seconds:

# Install cookiecutter
brew install cookiecutter  # or: pip install cookiecutter

# Generate a new service
cookiecutter gh:go-coldbrew/cookiecutter-coldbrew

# Build and run
cd MyService/
make run

Your service starts with all of these endpoints ready:

Define Once, Get Everything

Your API is defined once in protobuf — ColdBrew generates everything else:

rpc Echo(EchoRequest) returns (EchoResponse) {
    option (google.api.http) = {
        post: "/api/v1/echo"
        body: "*"
    };
}

This single definition gives you:

• gRPC endpoint on :9090 — with reflection for grpcurl and Postman
• REST endpoint at POST /api/v1/echo on :9091 — via grpc-gateway
• Swagger UI at /swagger/ — interactive API docs from your proto
• Prometheus metrics — per-method latency, error rate, and request count
• Distributed tracing — automatic span creation through the interceptor chain

Run buf generate — it creates typed Go interfaces from your proto definitions. The compiler ensures every RPC method is implemented, so API changes are caught at build time, not runtime. Just fill in your business logic and make run. Logging, tracing, metrics, health checks, and graceful shutdown are wired automatically. See the full pipeline for details.

How It Works

                    ┌─────────────────────────────────────────┐
                    │              ColdBrew Core               │
   HTTP Request ──► │  ┌─────────┐    ┌────────────────────┐  │
                    │  │  HTTP    │    │  Interceptor Chain  │  │
                    │  │ Gateway  │──► │                     │  │
                    │  │ (grpc-  │    │  ► Response Time    │  │
   gRPC Request ──► │  │ gateway)│    │  ► Trace ID         │  │
                    │  └─────────┘    │  ► OpenTelemetry     │  │
                    │       │         │  ► Prometheus        │  │
                    │       ▼         │  ► Error Notify      │  │
                    │  ┌─────────┐    │  ► Panic Recovery    │  │
                    │  │  gRPC   │──► │                     │  │──► Your Handler
                    │  │ Server  │    │                     │  │
                    │  └─────────┘    └────────────────────┘  │
                    │                                         │
                    │  /metrics  /healthcheck  /debug/pprof   │
                    └─────────────────────────────────────────┘

Packages

ColdBrew is modular — use the full framework or pick individual packages:

Each package can be used independently — you don’t need core to use errors or log.

Don’t Repeat Yourself — Focus on Business Logic

Every Go microservice needs health probes, Prometheus metrics, structured logging, distributed tracing, graceful shutdown, and panic recovery. Without a framework, teams copy-paste this infrastructure into every service — and each copy drifts slightly, making debugging and onboarding harder.

ColdBrew handles all of it. You write business logic, ColdBrew handles everything else:

New services inherit all of this automatically via the cookiecutter template — zero boilerplate to write, zero infrastructure to maintain.

Built on battle-tested libraries

ColdBrew composes proven Go libraries — not replacements:

Next Steps

• Getting Started — Create your first ColdBrew service
• How-To Guides — Step-by-step guides for common tasks
• Production Deployment — Kubernetes, health probes, tracing, and graceful shutdown
• Integrations — Set up monitoring, tracing, and error tracking
• FAQ — Common questions and answers