Building a microservice with servo

A step-by-step, from-scratch build of a real order-management service — HTTP API, JWT auth, Postgres, Redis, NATS, Prometheus metrics, OpenTelemetry tracing, a circuit breaker, a full test suite, CI/CD, and a Docker deployment — using servo to wire and run all of it.

Every chapter’s code lives in examples/tutorial, a real, separate Go module you can cd into and run at every step. Nothing in these pages is invented: every code block is copied from that module, and every command’s output shown here was actually run.

Why this exists

servo’s own README and examples/basic show the mechanics — how one constructor gets wired to another, what a spec file looks like, what servo generate produces. What they don’t show is what it’s like to build something with real weight to it: a service with a database, a cache, an event to publish, a login flow, tests at three different levels, and a pipeline that ships it. That gap — “I understand what servo does” to “I could build a real service with it” — is what this tutorial is for. Every chapter adds one layer or concern to the same running service, in the order you’d actually add them, so by the last chapter nothing is hypothetical: it’s a service you’ve built, one working piece at a time, that happens to also be a complete reference for how the pieces fit together.

How to read this

Each chapter follows the same shape: what problem this layer solves and why it exists, the real code that solves it (with enough surrounding explanation that you’re not just staring at syntax), a diagram where the shape of something is easier to see than to describe, a “try it yourself” section with commands you can actually run, then diagnostics, do’s and don’ts, and pointers to alternatives. Read chapters in order the first time — each one builds on code the previous ones already wrote. After that, they hold up fine as standalone reference.

Who this is for

You should be comfortable writing Go and using go test, but this tutorial assumes nothing about prior exposure to dependency injection, microservice architecture, or any of the specific libraries used (Postgres, Redis, NATS, JWT, Prometheus, OpenTelemetry). Each is introduced when it’s first needed, with a short “what and why” before the code.

Prerequisites

• Go 1.27 or newer (go version)
• Docker with the docker compose plugin, for running Postgres, Redis, and NATS locally
• curl (or any HTTP client) for the “try it yourself” sections
• No cloud account of any kind is required — everything runs on your machine

What you’ll build

flowchart TB
    Client(["HTTP client"])

    subgraph api["API layer"]
        Router["Router + middleware<br/>(auth, logging, recovery, rate limit)"]
    end

    subgraph svc["Service layer"]
        OrderService
    end

    subgraph data["Data"]
        PG[("Postgres")]
        Redis[("Redis")]
    end

    subgraph msg["Messaging"]
        NATS[("NATS")]
        Notifier["notifier<br/>(subscriber)"]
    end

    Client -->|"Bearer JWT"| Router
    Router --> OrderService
    OrderService -->|"read/write orders"| PG
    OrderService -->|"cache-aside reads"| Redis
    OrderService -->|"publish OrderPlaced"| NATS
    NATS -->|"consume"| Notifier

A user logs in, gets a JWT, and can place and view orders. Placing an order writes to Postgres, invalidates the cache, and publishes an OrderPlaced event; a separate notifier component consumes that event to show the “other side” of an event-driven system without needing an actual second service. Every arrow in that diagram is a real dependency servo resolves and wires for you — nothing here is assembled by hand.

Chapters

Read them in order the first time through — each one assumes the code from the previous chapters already exists. After that, they stand alone well enough to use as reference.