README.md

grpc-starter-kit

Microservices starter kit for Golang, aims to be developer friendly.
An open source framework for building and deploying distributed applications. This template monorepo style project allows you to write your application as a modular monolith and deploy it as a set of microservices.

Build Status

Quality

Overview

What you get

• Monorepo - Sharing Code Between Microservices
• gRPC microservices
• Versatile ingress gateway based on Envoy with Config Manager esp-v2
• Proxy-less Service Discovery and xDS based gRPC Load Balancer with Traffic Director
• Input Validation with protoc-gen-validate (PGV)
• Add/replace struct tags on generated protobuf messages protoc-gen-gotag (PGGT)
• Config - Pluggable Sources, Mergeable Config, Environment Overlays
• Customizable Logging
• Flexible errors lib: PII-free, gRPC middleware, opt-in Sentry.io reporting
• Graph-Based ORM ent
• CRUD API with ent
• Dependency injection Container, Try wire next?
• Adaptive System Protection / Adaptive concurrency limits with Alibaba's Sentinel, Netflix's concurrency-limits, go-concurrency-limits
• multi-stage-multi-target Dockerfile
• Reproducible builds and Verifiable Builds with GoReleaser
• One Step build/publish/deploy with ko
• BuildInfo with govvv
• Switch to Bazel Build
• Linting with GolangCI linters aggregator
• Linting Protos with Buf
• Linting rest with super-linter
• CICD Pipelines with GitHub Actions
• Kubernetes Matrix Deployment with Kustomize
• Add k8s healthchecks with cmux
• Feature Flags & Feature Gating (enable/disable with zero cost)
• Observability via OpenTelemetry
• Service Mesh with Istio
• GraphQL Gateway with gqlgen, rejoiner,gqlgen
• Graceful / zero downtime upgrades tableflip
• Cache — Ephemeral key-value storage with TTLs
• Secondary Index — Ephemeral Index with Redis Search
• Crypto — App-level data encryption/decryption with Key Management
• Auth — API Authentication with OpenID Connect, JWT, WebAuthN/Passwordless Login
• Zero Trust or BeyondProd style e2e Security
• mTLS
  • Option 1 (noCert): With Application LayerTransport Security (ALTS)
  • Option 2 (autoCert): With AutoCert
  • Option 3 (Step xDS): With Smallstep's Secret Discovery Service SDS
• supply-chain GoReleaser + Go Mod proxying + Cosign keyless signing + Syft SBOM generation example.
• Multi-arch container image
• gkit
• Continuous Profiling for Go Applications with Pyroscope

Getting Started

Prerequisite

Refer prerequisites docs

Initial Setup

Also Refer scaffolding docs

clone the repo

git clone https://github.com/xmlking/grpc-starter-kit ~/Developer/Work/go/grpc-starter-kit
# pull dependencies (when every time `go.mod` changed)
go mod download

Run

Database

By default, this project use embedded sqlite3 database. if you want to use postgreSQL,

• start postgres via docker-compose command provided below
• uncomment postgres import statement and comment sqlite in main.go
• start micro server with export export CONFY_FILES=/config/config.yml,/config/config.pg.yml flag
  i.e., CONFY_FILES=/config/config.yml,/config/config.pg.yml go run service/account/main.go

# to start postgres in foreground
docker-compose up postgres
# to stop postgres
docker-compose down
# if needed, remove `postgres_data` volume to recreate database next time, when you start.
docker system prune --volumes

Services

Node: --server_address=localhost:5501x --broker_address=localhost:5502x required only when you are behind VPN a.k.a Work From Home

# dev mode
make run-recorder

make run-emailer

make run-greeter

make run-account

# experiments 
make run-cedemo
make run-play
make run-xds

optionally specify any Confy environment variable

```shell
export CONFY_ENV=production
export CONFY_FILES=/config/config.yml
# (or) export CONFY_FILES=/config/config.yml,/config/config.pg.yml
export CONFY_DEBUG_MODE=true
export CONFY_VERBOSE_MODE=true
export CONFY_SILENT_MODE=true
export CONFY_ENV=production

export CONFY_ENV_PREFIX=APP
export APP_FEATURES_TLS_ENABLED=true
make run-account

Test

Refer testing docs

GitOps

Make

Refer makefile docs

Docker

Refer docker docs

Release

Refer releasing docs

Deploy

make docker DOCKER_REGISTRY=ghcr.io DOCKER_CONTEXT_PATH=xmlking/grpc-starter-kit
docker rmi $(docker images -f "dangling=true" -q)

# make kustomize OVERLAY=e2e NS=default VERSION=v0.1.0-440-g6c7fb7a
make kustomize
kubectl apply -f build/kubernetes.yaml

POD_NAME=$(kubectl get pods  -lapp.kubernetes.io/name=account-srv -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f -c srv $POD_NAME

kubectl delete -f build/kubernetes.yaml

Reference

Project Docs

1. prerequisites
2. scaffolding
3. makefile
4. testing
5. docker
6. gitops
7. Protobuf Style Guide
8. Google Protobuf Style Guide
9. Spine Protobuf Style Guide

External Docs

1. Go Repo Layout
2. examples - example usage code for micro
3. microhq - a place for prebuilt microservices
4. explorer - which aggregates micro based open source projects
5. micro-plugins extensible micro plugins
6. step-by-step-guide-micro
7. micro-in-cn
8. Platform Web
9. grpc template
10. Simple API backed by PostgresQL, Golang and gRPC
11. securing gRPC connections with TLS via certify
12. Google Service Weaver: A Framework for Writing Distributed Applications

🔗 Credits

• atlas-app-toolkit
• dapr
• goyave