Description
Golang API Starter Kit
================
[![Build Status](https://travis-ci.org/vardius/go-api-boilerplate.svg?branch=master)](https://travis-ci.org/vardius/go-api-boilerplate)
[![Go Report Card](https://goreportcard.com/badge/github.com/vardius/go-api-boilerplate)](https://goreportcard.com/report/github.com/vardius/go-api-boilerplate)
[![codecov](https://codecov.io/gh/vardius/go-api-boilerplate/branch/master/graph/badge.svg)](https://codecov.io/gh/vardius/go-api-boilerplate)
[![](https://godoc.org/github.com/vardius/go-api-boilerplate?status.svg)](http://godoc.org/github.com/vardius/go-api-boilerplate)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/vardius/go-api-boilerplate/blob/master/LICENSE.md)
[![baker](https://opencollective.com/go-api-boilerplate/tiers/backer/badge.svg?label=backer&color=brightgreen)](https://opencollective.com/go-api-boilerplate/contribute/backer-10349/checkout)
[![sponsor](https://opencollective.com/go-api-boilerplate/tiers/sponsor/badge.svg?label=sponsor&color=brightgreen)](https://opencollective.com/go-api-boilerplate/contribute/sponsor-10350/checkout)
Go Server/API boilerplate using best practices, DDD, CQRS, ES, gRPC.
Table of Contents
- [About](#about)
- [Documentation](#documentation)
- [Example](#example)
- [Quick start](#quick-start)
- [Build release](#build-release)
- [Deploy release](#build-release)
- [Dashboard](#dashboard)
- [Domain](#domain)
- [Dispatching command](#dispatching-command)
- [View](#view)
- [Public routes](#public-routes)
- [Protected routes](#protected-routes)
- [Sponsoring](#sponsoring)
ABOUT
==================================================
The main purpose of this project is to provide boilerplate project setup using 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.
![Dashboard](../master/.github/kubernetes-dashboard-overview.png)
![Dashboard](../master/.github/kubernetes-dashboard-pods.png)
Key concepts:
1. Rest API
2. [Docker](https://www.docker.com/what-docker)
3. [Kubernetes](https://kubernetes.io/)
4. [Helm chart](https://helm.sh/)
5. [gRPC](https://grpc.io/docs/)
6. [Domain Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) (DDD)
7. [CQRS](https://martinfowler.com/bliki/CQRS.html)
8. [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)
9. [Hexagonal, Onion, Clean Architecture](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/)
10. [oAuth2](https://github.com/go-oauth2/oauth2)
Worth getting to know packages used in this boilerplate:
1. [gorouter](https://github.com/vardius/gorouter)
2. [message-bus](https://github.com/vardius/message-bus)
3. [gollback](https://github.com/vardius/gollback)
4. [shutdown](https://github.com/vardius/shutdown)
5. [pubsub](https://github.com/vardius/pubsub)
DOCUMENTATION
==================================================
* [Wiki](https://github.com/vardius/go-api-boilerplate/wiki)
* [Package level docs](https://godoc.org/github.com/vardius/go-api-boilerplate#pkg-subdirectories)
* [Getting Started](https://github.com/vardius/go-api-boilerplate/wiki/1.-Getting-Started)
* [Installing and Setting up](https://github.com/vardius/go-api-boilerplate/wiki/2.-Installing-and-Setting-up)
* [Configuration](https://github.com/vardius/go-api-boilerplate/wiki/3.-Configuration)
* [Guides](https://github.com/vardius/go-api-boilerplate/wiki/4.-Guides)
EXAMPLE
==================================================
## Quick start
### Build release
```sh
make docker-build BIN=auth
make docker-build BIN=migrate
make docker-build BIN=user
```
### Deploy release
```sh
make helm-install
```
## Dashboard
https://go-api-boilerplate.local/dashboard/#!/overview?namespace=go-api-boilerplate
## Domain
### Dispatching command
Send example JSON via POST request
```sh
curl -sSL -D -d '{"email":"[email protected]"}' -H "Content-Type: application/json" -X POST https://go-api-boilerplate.local/users/dispatch/register-user-with-email -o /dev/null --insecure
```
## View
### Public routes
Get user details [https://go-api-boilerplate.local/users/34e7ed39-aa94-4ef2-9422-401bba9fc812](https://go-api-boilerplate.local/users/34e7ed39-aa94-4ef2-9422-401bba9fc812)
```json
{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812","email":"[email protected]"}
```
Get list of users [https://go-api-boilerplate.local/users?page=1&limit=10](https://go-api-boilerplate.local/users?page=1&limit=10)
```json
{"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://go-api-boilerplate.local/users/me](https://go-api-boilerplate.local/users/me).
```json
{"code": "401","message": "Unauthorized"}
```
Request access token for user
```sh
curl -sSL -D -d '{"id":"34e7ed39-aa94-4ef2-9422-401bba9fc812"}' -H "Content-Type: application/json" -X POST https://go-api-boilerplate.local/users/dispatch/request-user-access-token -o /dev/null --insecure
```
Get your access token from user pod event handler logs.
Access protected route using auth token [https://go-api-boilerplate.local/users/me?authToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyXHUwMDE277-977-977-977-9IiwiZXhwIjoxNTU5NjEwOTc2LCJzdWIiOiIzNGU3ZWQzOS1hYTk0LTRlZjItOTQyMi00MDFiYmE5ZmM4MTIifQ.pEkgtDAvNh2D3Dtgfpu4tt-Atn1h6QwMkDhz4KpgFxNX8jE7fQH00J6K5V7CV063pigxWhOMMTRLmQdhzhajzQ](https://go-api-boilerplate.local/users/me?authToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJyXHUwMDE277-977-977-977-9IiwiZXhwIjoxNTU5NjEwOTc2LCJzdWIiOiIzNGU3ZWQzOS1hYTk0LTRlZjItOTQyMi00MDFiYmE5ZmM4MTIifQ.pEkgtDAvNh2D3Dtgfpu4tt-Atn1h6QwMkDhz4KpgFxNX8jE7fQH00J6K5V7CV063pigxWhOMMTRLmQdhzhajzQ)
```json
{"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](https://github.com/vardius/go-api-boilerplate/issues) to manage them.
## π¨π»βπ»π©πΎβπ» Core Team:
RafaΕ Lorenz
## π₯ Backers
Support us with a monthly donation and help us continue our activities.
## π₯ Sponsors
Proudly sponsored by [Open Collective sponsors](https://opencollective.com/go-api-boilerplate#sponsor).
- π₯ [Contribute on Open Collective](https://opencollective.com/go-api-boilerplate#sponsor)
Golang API Starter Kit alternatives and similar packages
Based on the "Server Applications" category.
Alternatively, view Golang API Starter Kit alternatives based on common mentions on social networks and blogs.
-
etcd
Distributed reliable key-value store for the most critical data of a distributed system -
Caddy
Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS -
Vault
A tool for secrets management, encryption as a service, and privileged access management -
consul
Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure. -
apex
Build, deploy, and manage AWS Lambda functions with ease (with Go support!). -
SFTPGo
Fully featured and highly configurable SFTP server with optional HTTP/S, FTP/S and WebDAV support - S3, Google Cloud Storage, Azure Blob -
RoadRunner
π€― High-performance PHP application server, process manager written in Go and powered with plugins -
Ponzu
Headless CMS with automatic JSON API. Featuring auto-HTTPS from Let's Encrypt, HTTP/2 Server Push, and flexible server framework written in Go. -
Jocko
Kafka implemented in Golang with built-in coordination (No ZK dep, single binary install, Cloud Native) -
flipt
Enterprise-ready, GitOps enabled, CloudNative feature management solution -
algernon
Small self-contained pure-Go web server with Lua, Teal, Markdown, Ollama, HTTP/2, QUIC, Redis and PostgreSQL support -
discovery
A registry for resilient mid-tier load balancing and failover. -
Flagr
Flagr is a feature flagging, A/B testing and dynamic configuration microservice -
Key Transparency
A transparent and secure way to look up public keys. -
Trickster
Open Source HTTP Reverse Proxy Cache and Time Series Dashboard Accelerator -
Rendora
dynamic server-side rendering using headless Chrome to effortlessly solve the SEO problem for modern javascript websites -
jackal
π¬ Instant messaging server for the Extensible Messaging and Presence Protocol (XMPP). -
GeoDNS in Go
DNS server with per-client targeted responses -
go-feature-flag
GO Feature Flag is a simple, complete and lightweight self-hosted feature flag solution 100% Open Source. ποΈ -
SDNS
A high-performance, recursive DNS resolver server with DNSSEC support, focused on preserving privacy. -
Euterpe
Self-hosted music streaming server πΆ with RESTful API and Web interface. Think of it as your very own Spotify! βοΈπ§ -
Walrus
π₯ Fast, Secure and Reliable System Backup, Set up in Minutes. -
goproxy
π¦ goproxy is a proxy server which can forward http or https requests to remote servers./ goproxy ζ―δΈδΈͺεε代ηζε‘ε¨οΌζ―ζ转ε http/https θ―·ζ±γ -
Eru
Eru, a simple, stateless, flexible, production-ready orchestrator designed to easily integrate into existing workflows. Can run any virtualization things in long or short time. -
Aegis
Serverless Golang deploy tool and framework for AWS Lambda -
marathon-consul Β Β Β
Integrates Marathon apps with Consul service discovery. -
cortex-tenant
Prometheus remote write proxy that adds Cortex/Mimir tenant ID based on metric labels -
dummy
Run mock server based off an API contract with one command -
go-proxy-cache
Simple Reverse Proxy with Caching, written in Go, using Redis. -
lets-proxy2
Reverse proxy with automatically obtains TLS certificates from Let's Encrypt -
Simple CRUD App w/ Gorilla/Mux, MariaDB
Simple CRUD Application with Go, Gorilla/mux, MariaDB, Redis. -
psql-streamer
Stream database events from PostgreSQL to Kafka -
nginx-prometheus
Turn Nginx logs into Prometheus metrics -
simple-jwt-provider
Simple and lightweight provider which exhibits JWTs, supports login, password-reset (via mail) and user management. -
protoxy
A proxy server than converts JSON request bodies to protocol buffers -
autobd
autobd is an automated, networked and containerized backup solution -
go-fitbit
Fitbit API for Go to fetch, add, update and delete data on Fitbit using REST API -
Gin Healthcheck
Lightweight, customizable healthcheck endpoint for Gin Framework
InfluxDB - Power Real-Time Data Analytics at Scale
Do you think we are missing an alternative of Golang API Starter Kit or a related project?
README
π§° Golang API Starter Kit
Go Server/API boilerplate using best practices, DDD, CQRS, ES, gRPC.
Table of Contents
<!-- toc -->
- About
- Documentation
- Example
- Sponsoring <!-- tocstop -->
π 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](cmd/user/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](k8s/.docker/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.
π [License](LICENSE.md)
*Note that all licence references and agreements mentioned in the Golang API Starter Kit README section above
are relevant to that project's source code only.