π§°
Golang API Starter Kit
Go Server/API boilerplate using best practices, DDD, CQRS, ES, gRPC.
Table of Contents
π
ABOUT
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.
Key concepts:
- Rest API
- Docker
- Kubernetes
- Helm chart
- Terraform
- gRPC
- Domain Driven Design (DDD)
- CQRS
- Event Sourcing
- Hexagonal, Onion, Clean Architecture
- oAuth2
Worth getting to know packages used in this boilerplate:
π
DOCUMENTATION
π«
EXAMPLE
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.
##
127.0.0.1 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.
v1.0.0+auth
v1.0.0+user
v1.0.0+web
v1.0.0+migrate
Replace image details in main.yaml
image:
- repository: go-api-boilerplate-user
+ repository: docker.pkg.github.com/vardius/go-api-boilerplate/go-api-boilerplate-user
- tag: latest
+ tag: 1.0.0
pullPolicy: IfNotPresent
repeat for all services and migrate init containers.
Private Registry
docker login
Copy docker config
cp ~/.docker/config.json ./k8s/.docker/config.json
Verify config.json
Deploy release
make terraform-install
Destroy
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
Output:
Finalizers: [kubernetes.io/pvc-protection]
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.
Domain
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
View
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.
![[question] domain pollution](https://avatars.githubusercontent.com/u/3648733?v=4)
