Getting started
From an empty folder to a humus service that runs with go run and passes a test that runs the whole App with humustest.Start, with nothing but a Go toolchain.
Humus
An opinionated Go framework for building services on bedrock’s process model: HTTP and OpenAPI APIs, gRPC services, jobs, Kafka and RabbitMQ consumers and Kubernetes controllers, with telemetry, health and graceful shutdown built in.
Humus is a Go framework for services that run on Kubernetes: HTTP and OpenAPI APIs, gRPC services, jobs, Kafka and RabbitMQ consumers and Kubernetes controllers. It runs each of them the same way, on bedrock’s process model, with OpenTelemetry, health probes and a graceful shutdown that fits inside Kubernetes’ termination budget.
What a service looks like
A service’s main is one call, func main() { humus.Main(app.Init) }, where
app.Init is the service’s own Init. Init sources the service’s
settings, builds its dependencies, registers their release, and returns the
Services the App runs until it shuts down:
func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
out := s.Process.Stdout
s.OnStop(func(context.Context) error {
_, err := fmt.Fprintln(out, "on stop: close the cache")
return err
})
s.OnStop(func(context.Context) error {
_, err := fmt.Fprintln(out, "on stop: close the queue")
return err
})
if _, err := config.Env(s.Process.Environment, "DATABASE_URL").Read(ctx); err != nil {
return nil, err // exit 78: init: config DATABASE_URL: not found
}
return []humus.Service{newServer(out)}, nil
}
A service type’s package, such as httpserver or queue/kafka, builds the
Services an Init returns. The App lifecycle
explains what the App does with them.
The reading order
The sections of this site are meant to be read in order, and every page links to the next one:
- Getting started: from an empty folder to a humus service that runs and passes a test. Start here.
- Fundamentals: the App lifecycle, configuration, telemetry, health and testing, which every service shares.
- Service types: one section for each kind of service humus runs.
- Calling dependencies: the HTTP and gRPC clients a service calls its dependencies with.
- Hardening: authentication and authorization, and failure injection.
- Walkthroughs: a production-ready application of each service type, built step by step.
To start from a service type instead, find it here: