README

PACE Bricks Build Status Coverage Status

Opinionated microservice kit to help developers to build microservices with go.

Opinions

A pace/bricks microservice is:

  • built as a docker container
  • deployed into a kubernetes cluster
    • support for the termination log
  • configured using environment variables (TWELVE-FACTOR APP)
  • monitored using prometheus
  • reports errors to sentry
  • samples traces to jaeger
  • logs to stdout using json deployed kubernetes otherwise human readable
  • offers health endpoints
  • connects to backend services
    • postgres (logging, metrics, tracing, health)
    • redis (logging, metrics, tracing, health)
    • s3 (logging, metrics, tracing, health)
    • http (logging, metrics, tracing, retries)
  • provides two commands control and daemon
  • provides a RESTful API
    • code is generated from the OpenAPIv3 spec
    • authenticated via OAuth2
    • encoded using json:api
    • that supports logging, tracing and metrics

Install

go get github.com/pace/bricks/cmd/pb

Usage

pb -h

Contributing

Read our contributors guide.

Requirements

  • A working go installation
  • A working git installation

Testing

  • Use make test to test without dependencies
  • Use docker-compose run testserver make integration to test with dependencies
  • Use make testserver to start a testserver that will be started with dependencies. In order to update the server one need to docker-compose restart testserver

Environment variables for the pb command

Variable Description
PACE_BRICKS_EDITOR   The path to the editor that should be used for opening a project. Defaults to $EDITOR.
PACE_BRICKS_PATH The path where new project should be created. Defaults to $HOME/PACE.
Expand ▾ Collapse ▴

Directories

Path Synopsis
backend/objstore
backend/postgres Package postgres helps creating PostgreSQL connection pools
backend/queue
backend/redis Package redis helps creating redis connection pools
cmd/pb
http Package http implements the basic pace microservice handlers and a standard microservice server configured via environment variables.
http/jsonapi Package jsonapi provides a serializer and deserializer for jsonapi.org spec payloads.
http/jsonapi/generator Package generator translates an OpenAPIv3 specification into working go code that handles marshalling, error handling, parameter parsing and validation.
http/jsonapi/runtime Package runtime contains functions for marshalling, error handling, parameter parsing and validation.
http/longpoll
http/oauth2 Package oauth2 provides a middelware that introspects the auth token on behalf of PACE services and populate the request context with useful information when the token is valid, otherwise aborts the request.
http/oauth2/middleware
http/oidc
http/security
http/security/apikey
http/transport
internal/service
internal/service/generate
locale The http locale package helps to transport and use the localization information in a microservice landscape.
maintenance/errors
maintenance/errors/raven Package raven implements a client for the Sentry error logging service.
maintenance/health Package health implements simple checks for readiness and liveness that will be invoked by the loadbalancer frequently
maintenance/health/servicehealthcheck
maintenance/log
maintenance/log/hlog Package hlog provides a set of http.Handler helpers for zerolog.
maintenance/metric Package metric returns the prometheus metrics handler
maintenance/metric/jsonapi Package jsonapi implements the json api related metrics documented here: https://lab.jamit.de/pace/web/meta/wikis/concept/metrics#m2-microservice-any-pace-microservice
maintenance/terminationlog Package terminationlog helps to fill the kubernetes termination log.
maintenance/tracing
maintenance/tracing/wire
maintenance/util
pkg/cache
pkg/cache/testsuite
pkg/context
pkg/isotime
pkg/routine Package routine helps in starting background tasks.
pkg/synctx Package synctx implements helpers for the context package on top of the sync package.
test/livetest Package livetest implements a set of helpers that ease writing of a sidecar that tests the functions of a service.
tools/jsonapigen
tools/testserver
tools/testserver/simple Code generated by github.com/pace/bricks DO NOT EDIT.