___ ___ _____   _____ ___ ___ ___  _   ___ _  __
/ __| __| _ \ \ / /_ _/ __| __| _ \/_\ / __| |/ /
\__ \ _||   /\ V / | | (__| _||  _/ _ \ (__| ' <
|___/___|_|_\ \_/ |___\___|___|_|/_/ \_\___|_|\_\

servicepack

Clone-and-own Go service framework: run related services together locally so you can debug the whole fucking thing in one process, then deploy it as one binary or split those services into separate microservices when that makes sense.

This is a template repo, not a go get library. It gives a new Go project a concurrent service supervisor, lifecycle runner, Docker-first build/test workflow, generated service registration, and sane places to customize it.

Quick start

Use a fresh clone. make own deliberately removes the clone's Git history, rewrites its module path, removes shipped example services (except hello-world), initializes a new repository, and creates its first commit.

git clone https://github.com/psyb0t/servicepack.git my-service
cd my-service
make own MODNAME=github.com/yourname/my-service
make service NAME=worker
make build
./build/my-service run

The normal Make targets use Docker, so you do not need a matching host Go toolchain for make build, make test, or make lint. Docker must be available. See getting started before pointing it at a clone you care about.

Want to poke the shipped examples first?

git clone https://github.com/psyb0t/servicepack.git
cd servicepack
make run-dev

The examples show retries, dependency ordering, readiness, allowed failures, and a deliberate crash that stops the process after roughly 36 seconds.

Why this exists

Local composition is the useful bit: workers, API servers, migrations, and other process-level services can run together with one signal path and one structured log stream. That is not a lifetime commitment to a monolith.

• One binary: ship the related services together when they genuinely share a release cadence and operational boundary.
• Separate deployables: move a service behind HTTP, gRPC, a queue, or another process boundary when it needs independent scaling, ownership, or failure isolation. Servicepack's in-process Dependent contract only coordinates services present in that binary; external dependencies belong in the service's own connection and retry logic.

Everyday workflow

Command	What it does
make service NAME=worker	Scaffold a service and regenerate registration.
make test	Run race-enabled tests in the development container.
make test-integration	Run uncached, race-enabled tests with Docker available to Testcontainers.
make test-coverage	Enforce the default 90% framework coverage floor.
make lint	Run shell and Go linting in Docker.
make build	Produce a static binary in build/, with binary name and source commit in log scope.
make docker-build	Build the production image.
make help	List every available target.

make servicepack-update updates the framework copy in a project made from this template. Read framework updates first; it expects a clean repository and creates a backup/update branch.

Documentation

Read this	For
Getting started	Turning a fresh clone into your project, then adding and running a service.
Services and lifecycle	Interface contracts, dependencies, retries, commands, filtering, logging, and shutdown.
Development	Docker-first Make targets, Testcontainers, coverage, builds, and overrides.
Architecture	The process topology, ownership boundaries, generated registration, and deployment choices.
Framework updates	Updating a clone safely and keeping project customizations out of the blast radius.
Service manager deep dive	Exact orchestration semantics and test conventions.
Runner deep dive	Signals, parent contexts, and shutdown deadline behavior.
Framework Make scripts	The updateable script layer and user overrides.

Project layout

cmd/                            entry point plus your init/CLI extension points
internal/app/                   application lifecycle wrapper
internal/pkg/service-manager/   concurrent service orchestration
internal/pkg/services/          your services and generated registration
pkg/runner/                     signal-aware lifecycle runner
scripts/make/servicepack/       updateable framework Make scripts
scripts/make/                   project-specific script overrides
docs/                           your operational and architectural docs
tests/                          your testcontainers harness and service tests

Agent integrations

Agent-facing setup and conventions live under .agents/skills/servicepack/. The skill is available through the psyb0t agents marketplace for Claude Code, Codex, and OpenClaw-compatible setups.

License

MIT. See LICENSE. Release history lives in CHANGELOG.md.