Awesome Open Source
Awesome Open Source

🧰 Golang API Starter Kit

Build Status Test Go Report Card codecov license baker sponsor


Go Server/API boilerplate using best practices, DDD, CQRS, ES, gRPC.

Table of Contents


The main purpose of this project is to provide boilerplate project setup using best practices, DDD, CQRS, ES, gRPC. Featuring kubernetes for both development and production environments. Allowing to work with environment reflecting production one, allowing to reduce any misconfigurations.

This is mono-repository of many services such as authentication or user domain. Each service has it own code base with exception of shared packages to simplify things for this boilerplate. Services communicate witch each other using gRPC. Each service might expose HTTP API for external communication or/and gRPC.

This project setup should reduce the time spent on environment configuration for the whole kubernetes cluster and/or each of microservice. Extracting each of services to own repository or keeping it as mono-repo should be a matter of preference.

Please look for comments like @TODO and @FIXME to better understand things than need attention.

Web UI example (React)

This boilerplate includes simple Web UI to demonstrate example interaction with API. Once deployed and hosts are set please visit https://api.go-api-boilerplate.local to access UI.

Web UI

Key concepts:

  1. Rest API
  2. Docker
  3. Kubernetes
  4. Helm chart
  5. Terraform
  6. gRPC
  7. Domain Driven Design (DDD)
  8. CQRS
  9. Event Sourcing
  10. Hexagonal, Onion, Clean Architecture
  11. oAuth2

Worth getting to know packages used in this boilerplate:

  1. gorouter
  2. message-bus
  3. gollback
  4. shutdown
  5. pubsub
  6. pushpull
  7. gocontainer



Quick start

Localhost alias

Edit /etc/hosts to add localhost alias

➜ go-api-boilerplate git:(master) cat /etc/hosts
# Host Database
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
## go-api-boilerplate.local api.go-api-boilerplate.local maildev.go-api-boilerplate.local mysql.go-api-boilerplate.local

Build release

Local image

make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
make docker-build BIN=web

GitHub Package Registry

Creating tag with metadata will trigger github workflow and publish docker image to GitHub Package Registry.

Tag v1.0.0+user will trigger build for user service releasing 1.0.0 docker image tag. you can create release for all services in cmd directory.


Replace image details in main.yaml

-    repository: go-api-boilerplate-user
+    repository:
-    tag: latest
+    tag: 1.0.0
    pullPolicy: IfNotPresent

repeat for all services and migrate init containers.

Private Registry

Log in to Docker

docker login

Copy docker config

cp ~/.docker/config.json ./k8s/.docker/config.json

Verify config.json

Deploy release

make terraform-install


make terraform-destroy

If persistent volume is stack in terminating, this happens when persistent volume is protected. You should be able to cross verify this:

kubectl describe pvc PVC_NAME --namespace=go-api-boilerplate | grep Finalizers

Finalizers:    []

You can fix this by setting finalizers to null using kubectl patch:

kubectl patch pvc PVC_NAME --namespace=go-api-boilerplate -p '{"metadata":{"finalizers": []}}' --type=merge

Build tags

Build flags are used for different persistence layers. Please see services.go file for details. Provided layers are mysql, mongo and memory. If desired in similar way new layer can be easily added, following given patter.

go build -tags=persistence_mysql

Available build tags

  • persistence_mysql (mysql service container)
  • persistence_mongodb (mongodb service container)

Important persistence layer defaults to memory if no flag is provided (Docker image sets persistence_mysql flag), see each service Dockerfile for details.


Dispatching command

Send example JSON via POST request

curl -d '{"email":"[email protected]"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/user/user-register-with-email --insecure


Public routes

Get user details https://api.go-api-boilerplate.local/users/v1/34e7ed39-aa94-4ef2-9422-401bba9fc812

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"[email protected]"}

Get list of users https://api.go-api-boilerplate.local/users/v1?page=1&limit=10

{"page":1,"limit":20,"total":1,"users":[{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"[email protected]"}]}

Protected routes

Access protected route using auth token https://api.go-api-boilerplate.local/users/v1/me.

{"code": "401","message": "Unauthorized"}

Request access token for user

curl -d '{"email":"[email protected]"}' -H "Content-Type: application/json" -X POST https://api.go-api-boilerplate.local/users/v1/dispatch/user/user-request-access-token --insecure

Get your access token from mail catcher https://maildev.go-api-boilerplate.local.

Access protected route using auth token https://api.go-api-boilerplate.local/users/v1/me?authToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyXHUwMDE277-977-977-977-9IiwiZXhwIjoxNTU5NjEwOTc2LCJzdWIiOiIzNGU3ZWQzOS1hYTk0LTRlZjItOTQyMi00MDFiYmE5ZmM4MTIifQ.pEkgtDAvNh2D3Dtgfpu4tt-Atn1h6QwMkDhz4KpgFxNX8jE7fQH00J6K5V7CV063pigxWhOMMTRLmQdhzhajzQ

{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"[email protected]"}

💲 Sponsoring

🚀 Contributing

Want to contribute ? Feel free to send pull requests!

Have problems, bugs, feature ideas? We are using the github issue tracker to manage them.

👨🏻‍💻👩🏾‍💻 Core Team:

Rafał Lorenz

Marin Kirkov

👥 Backers

Support us with a monthly donation and help us continue our activities.

🥇 Sponsors

Proudly sponsored by Open Collective sponsors.

📜 License

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Go (172,393
Golang (172,393
Docker (99,724
Restful (29,187
Bootstrap (28,784
Kubernetes (25,998
Oauth2 (14,315
Microservice (12,351
Routes (8,847
Rpc (8,181
Registry (7,386
Grpc (5,323
Helm (4,907
Starter Kit (4,026
Ddd (2,602
Cqrs (1,960
Event Sourcing (1,135
Helm Charts (1,108
Oauth2 Server (282
Telepresence (30