Kratos Layout

Language: English | 中文

Kratos Layout is a starter template for building Go microservices with Kratos. It provides a ready-to-extend service structure with HTTP, gRPC, service discovery, data clients, observability, and protobuf-based API generation.

The sample service exposes a Greeter API:

GET /helloworld/{name}

What This Project Provides

• HTTP and gRPC servers powered by Kratos.
• Protobuf-first API definitions with generated HTTP/gRPC bindings.
• Wire-based dependency injection.
• Etcd service registration.
• MySQL and PostgreSQL clients through GORM.
• Redis client instrumentation.
• Kafka producer and consumer group setup.
• OpenTelemetry tracing and metrics.
• Prometheus metrics endpoint.
• pprof server for runtime profiling.
• Docker Compose environment for local infrastructure.

Project Structure

api/                 Protobuf API definitions and generated API code
cmd/server/          Application entrypoint and Wire assembly
configs/             Runtime configuration
internal/biz/        Business use cases and domain interfaces
internal/data/       Database, Redis, Kafka, and repository implementations
internal/server/     HTTP, gRPC, and pprof server setup
internal/service/    Transport-facing service implementations
internal/conf/       Configuration protobuf and generated Go code
internal/middleware/ Shared middleware
internal/registry/   Service registry setup
internal/trace/      OpenTelemetry setup
pkg/                 Reusable helper packages
third_party/         Protobuf dependencies

The application follows this dependency flow:

repo -> biz -> service -> server -> app

Requirements

• Go 1.25 or later, matching go.mod
• make
• protoc, when regenerating protobuf code
• Docker and Docker Compose, when running the full local stack

Quick Start With Docker Compose

Start the infrastructure and service:

docker compose up -d

The Compose file starts etcd, Jaeger, MySQL, PostgreSQL, Redis, Kafka, and the helloworld service image.

Default host ports:

Service	Host Port	Container Port
HTTP API	48000	8000
gRPC API	49000	9000
pprof	46060	6060
Jaeger UI	16686	16686
Etcd	42379	2379
MySQL	43306	3306
PostgreSQL	45432	5432
Redis	46379	6379
Kafka	49092	9094

Test the HTTP API:

curl http://localhost:48000/helloworld/kratos

Expected response:

{"message":"Hello kratos"}

Run Locally From Source

Install development tools:

make init

Build the project:

make build

Run the server:

./bin/server -conf configs

The default configs/config.yaml uses Docker service hostnames such as etcd, mysql, postgresql, redis, kafka, and jaeger. If you run the binary directly on your host machine, update the config to use localhost and the mapped ports from docker-compose.yaml, or run the binary inside the Compose network.

Common Commands

# Install code generation tools
make init

# Generate API protobuf code and OpenAPI output
make api

# Generate internal config protobuf code
make config

# Run go generate and tidy modules
make generate

# Run all generation tasks
make all

# Build all packages
make build

# Run tests
go test ./...

API Development

Edit API definitions under api/helloworld/v1/*.proto, then regenerate:

make api

Edit runtime configuration schema in internal/conf/conf.proto, then regenerate:

make config

If provider sets or dependency constructors change, regenerate Wire output:

make generate

Configuration

Runtime configuration is loaded from configs/config.yaml.

Important sections:

• server: HTTP, gRPC, and pprof addresses.
• registry: etcd endpoints for service registration.
• data.database: MySQL and PostgreSQL connection settings.
• data.redis: Redis clients and shards.
• data.kafka: Kafka brokers and consumer group.
• otel: tracing and metrics configuration.
• log: log file and rotation settings.
• bbr: rate limiting and overload protection settings.

Observability

• Metrics are exposed through the HTTP server at /metrics.
• Traces are exported to the OTLP endpoint configured in configs/config.yaml.
• The default Docker Compose stack includes Jaeger at http://localhost:16686.
• pprof is exposed on the configured pprof port.

Docker Image

Build the image locally:

docker build -t kratos-layout .

The Dockerfile builds the Go binary in a golang:1.25 builder image and runs it from a slim Debian runtime image.

License

This project is licensed under the MIT License. See LICENSE for details.