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.
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.
- Rest API
- Docker
- Kubernetes
- Helm chart
- gRPC
- Domain Driven Design (DDD)
- CQRS
- Event Sourcing
- Hexagonal, Onion, Clean Architecture
- oAuth2
Worth getting to know packages used in this boilerplate:
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.
##
127.0.0.1 go-api-boilerplate.local api.go-api-boilerplate.local maildev.go-api-boilerplate.local mysql.go-api-boilerplate.local
make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
make docker-build BIN=web
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.
v1.0.0+auth
v1.0.0+user
v1.0.0+web
v1.0.0+migrate
Replace image details in values.yaml
image:
- repository: go-api-boilerplate-user
+ repository: docker.pkg.github.com/vardius/go-api-boilerplate/user
- tag: latest
+ tag: 1.0.0
pullPolicy: IfNotPresent
repeat for all services and migrate
init containers.
If you want your k8sto Pull an Image from a Private Registry on your k8 machine login to docker:
docker login
Then create a secret in go-api-boilerplate
namespace as follows:
kubectl create secret generic regcred --from-file=.dockerconfigjson=.docker/config.json --type=kubernetes.io/dockerconfigjson --namespace=go-api-boilerplate
Set imagePullSecrets
in your values.yaml file (simply look for all occurrences and uncomment).
+ imagePullSecrets: regcred
Install Cert Manager
helm repo add jetstack https://charts.jetstack.io
helm repo update
make helm-dependencies
make helm-install
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/register-user-with-email --insecure
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]"}]}
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/request-user-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]"}
Want to contribute ? Feel free to send pull requests!
Have problems, bugs, feature ideas? We are using the github issue tracker to manage them.
![]() RafaΕ Lorenz |
![]() Marin Kirkov |
Support us with a monthly donation and help us continue our activities.
Proudly sponsored by Open Collective sponsors.