Golang API Starter Kit
The main purpose of the project was to provide the model project setup using best practices, DDD, CQRS, ES, gRPC. Provide Kubernetes configurations for development and production environments. Allows you to work with production-reflecting environments to reduce any misconfiguration.
This is a single mono-repository for many services, such as authentication or user domains. In addition to shared packages, each service has its own code base to simplify this boilerplate. Services communicate with each other through gRPC. Each service may expose HTTP apis for external communication and/or gRPC.
This project setup should reduce the environment configuration time for the entire Kubernetes cluster and/or each microservice. Extracting each service into its own repository or keeping it as mono-repo should be a matter of preference.
Web UI Example (React)
This sample includes a simple Web UI to demonstrate sample interaction with the API. Once hosts is deployed and set up, go to api.go-api-boilerplate.local to access the UI.
A key concept
- Rest API
- Docker
- Kubernetes
- Helm chart
- Terraform
- gRPC
- Domain Driven Design (DDD)
- CQRS
- Event Sourcing
- Hexagonal, Onion, Clean Architecture
- oAuth2
It’s worth looking at the packages used in this boilerplate:
- gorouter
- message-bus
- gollback
- shutdown
- pubsub
- pushpull
- gocontainer
📚 document
- Wiki
- Package level docs
- Getting Started
- Installing and Setting up
- Configuration
- Guides
Quick start
Localhost alias
Edit /etc/hosts to add the 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.localCopy the code
Build release
Local image
make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
make docker-build BIN=web
Copy the code
GitHub Package Registry
Creating a tag using metadata triggers the Github Workflow and publishes the Docker image to the Github Package Registry.
The tag v1.0.0+user triggers the build of the User service, publishing the 1.0.0 Docker Image Tag. You can create releases for all services in the CMD directory.
V1.0.0 + auth v1.0.0 + user v1.0.0 + web v1.0.0 + migrateCopy the code
Replace the 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
Copy the code
Repeat this operation and Migrate Init Containers for all services.
Private Registry
Log in to the Docker
docker login
Copy the code
Copy the docker config
cp ~/.docker/config.json ./k8s/.docker/config.json
Copy the code
Verify the config. Json
Deploy release
make terraform-install
Copy the code
Destroy
make terraform-destroy
Copy the code
If persistent volumes stack at termination, this happens when the persistent volumes are 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]
Copy the code
You can solve this problem by using Kubectl patch to set finalizers to NULL:
kubectl patch pvc PVC_NAME --namespace=go-api-boilerplate -p '{"metadata":{"finalizers": []}}' --type=merge
Copy the code
Build tags
Build Flags is used for different persistence layers. See the services.go file for more information. The layers provided are mysql, Mongo, and Memory. If desired, new layers can be easily added in a similar manner, following a given pattern.
go build -tags=persistence_mysql
Copy the code
Build tags available
- persistence_mysql (mysql service container)
- persistence_mongodb (mongodb service container)
Persistence_mysql flag is set to memory by default. See per-service Dockerfile for details.
Domain (Domain)
Dispatching Command
Send sample 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
Copy the code
The View (View)
Public routes
Access to the user details API. Go – API – boilerplate. Local/users/v1/34…
{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812"."email":"[email protected]"}
Copy the code
Access to the user list API. Go – API – boilerplate. Local/users/v1? Pa…
{"page":1."limit":20."total":1."users": [{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812"."email":"[email protected]"}}]Copy the code
Protected routes
Access to protected the route, using ` auth token API. Go – API – boilerplate. Local/users/v1 / me.
{"code": "401"."message": "Unauthorized"}
Copy the code
Request an 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
Copy the code
Get your access token maildev.go-api-boilerplate.local from Mail Catcher.
Using the auth token to access the protected routing API. Go – API – boilerplate. Local/users/v1 / me…
{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812"."email":"[email protected]"}
Copy the code