Quick start

Everything runs in Docker Compose on localhost. You don’t need a Kubernetes cluster, Helm, or an entry in /etc/hosts.

What you need

Docker with Compose v2, so that docker compose works.
Go 1.27.3 or later, to run the tests and tools outside Docker. An older Go, from 1.21 on, downloads it by itself.
The GitHub CLI, or use the Use this template button on GitHub instead of the first step.

Run it

Create your repository from the template and clone it:

gh repo create my-api --template vardius/go-api-boilerplate --private --clone
cd my-api

Give the module your own path. Go imports and buf.gen.yaml carry the template’s path, so replace it everywhere at once. The generated Connect code also holds it inside binary descriptors that a text replacement breaks, so regenerate that with make gen, then check that the tests pass:
Terminal window
```
go mod edit -module github.com/you/my-api
grep -rl github.com/vardius/go-api-boilerplate --include='*.go' --include='*.yaml' . \
  | xargs perl -pi -e 's#github.com/vardius/go-api-boilerplate#github.com/you/my-api#g'
make gen
go test -short ./...
```
Start everything and wait until each container reports healthy:
Terminal window
```
docker compose up --wait
```
This builds the auth and user services on the memory store, the web app behind its gateway, and Mailpit. There is nothing to configure first: compose.yaml sets development values inline.
Open localhost:8080 and sign in with any email address.
Open Mailpit at localhost:8025, open the message, and follow the link. You are signed in.

To stop everything:

docker compose down

Google sign-in stays off until you set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your shell before starting; compose passes both to the user service. Configuration shows how to get them.

Use MySQL or MongoDB

Each binary links exactly one store, chosen by a build tag. make up adds the database through an override file and rebuilds both services for it:

make up STORE=mysql
make up STORE=mongodb

STORE=mysql runs MySQL 9.7 and applies the migrations at start, which compose turns on with MIGRATE_ON_START=true. STORE=mongodb runs MongoDB as a single-node replica set, because multi-document transactions need one, and creates the indexes at start the same way. Stop either with the same STORE, such as make down STORE=mysql; it also removes the database volume. make up OBSERVABILITY=1 adds Grafana on localhost:3000, as Observability explains.

Work on the code

Command	What it does
`docker compose watch`	Rebuilds a service when its code changes.
`docker compose logs -f user`	Follows one service’s logs. `make logs` follows both services.
`go test -race ./...`	Runs every test. Tests that start MySQL or MongoDB containers need Docker.
`go test -short ./...`	Skips the container tests, for a quick run without Docker.
`make check`	Runs what CI runs, except the container tests and the end-to-end tests. Do this before you push.
`make gen`	Regenerates the Connect code and the configuration reference.
`make e2e`	Runs the end-to-end tests against the running stack.
`make`	Lists every target.

Common questions

Do I need Kubernetes to develop? No. Compose runs the whole system. The Helm chart is for deploying.

How do users sign up? There are no passwords. A user types an email address and gets a link with a one-time code. The first time a code is redeemed, the account is created. Typing an address alone creates nothing.

Where do the emails go? Locally, to Mailpit, which accepts everything and sends nothing on. In production, set the SMTP_* variables in Configuration.

Can I use go-micro, NATS or Kafka? You can, but nothing here needs a broker. If a side effect should reach another system, the outbox is where you would publish it.

Can I add another database, such as DynamoDB? Yes. Implement the store interfaces and pass the same contract suites the three built-in backends pass. See Event store and concurrency.

ArchitectureWhat happens on sign-in, and where the trust boundaries are.

Add a commandChange the domain: an event, a rule, a use case and its tests.