GitOps deployment for Docker Compose workloads across multiple SSH-reachable nodes — think "Flux for plain Docker hosts".
The name is a pun on the German dub of Back to the Future, where the Flux Capacitor is called "Fluxkompensator". kompensator continuously "compensates" the drift between the desired state in Git and the actual state running on your nodes.
kompensator watches one or more Git repositories that describe the desired state of your fleet (which image/tag should run for which app, on which nodes) and reconciles the actual state on each node to match it. Deployments use Docker Compose. Traffic switching during a Blue/Green deploy is handled by a pluggable proxy plugin.
- No daemon. Each node runs
kompensator reconcilefrom cron (~every minute) for a self-healing pull loop. The operator's CLI can trigger the same reconcile immediately over SSH. - Single binary, two roles. The same binary is the node agent and the controller/CLI; the role is detected from the local config.
- Git is the source of truth. Each node pulls its configured deployment repo with a read-only deploy key. Secrets stay out of Git (age-encrypted, delivered out of band).
- Small fleets. Targets a realistic 1–4 node setup; larger deployments should use Kubernetes or similar.
kompensator is in active development. It is built incrementally in phases — see docs/roadmap.md for what is implemented and what is planned.
go install github.com/kratecorg/kompensator/cmd/kompensator@latestRequires Go 1.24+.
git clone https://github.com/kratecorg/kompensator.git
cd kompensator
make build # produces ./bin/kompensatorDownload the binary for your platform from the Releases page.
kompensator [global flags] <command> [args]
Common commands:
| Command | Purpose |
|---|---|
reconcile [env [stack [project]]] |
Pull the deployment repo(s) and deploy on drift |
status [env] |
Show desired vs. running images |
pause / resume |
Suspend/resume reconciling during a delicate operation |
verify <env> |
Check from Git that every node reached the desired commit and is healthy |
check |
Audit a node/controller setup |
controller init / controller repo add |
Set up a controller home and its deployment repos |
node add / node remove |
Provision or deregister a node from the controller |
env list / stack list |
Show what the deployment repo defines and where it is placed |
env add / env stack add |
Create an environment and place stacks in it |
stack add / project add |
Scaffold a stack and its compose projects |
state set <env> <stack> <project> <service> <image>:<tag> |
Point a service at an image (the CI deploy call) |
secrets … |
Manage age-encrypted environment and file secrets |
completion <shell> |
Print a shell completion script (bash, zsh, fish) |
version |
Print the version |
Run kompensator help for the full command reference.
Completion is served by the binary itself, so it offers the environment, stack, project and node names read from the local deployment-repo checkout — not just the static command tree.
# bash
kompensator completion bash | sudo tee /etc/bash_completion.d/kompensator
# zsh
kompensator completion zsh > "${fpath[1]}/_kompensator"
# fish
kompensator completion fish > ~/.config/fish/completions/kompensator.fish| Document | Description |
|---|---|
| docs/README.md | Documentation index |
| docs/getting-started.md | Prerequisites and first setup (controller + remote nodes) |
| docs/architecture.md | System architecture, components, and diagrams |
| docs/concepts.md | Glossary and core concepts |
| docs/repository-layout.md | Layout of a GitOps deployment repo |
| docs/roadmap.md | Phased implementation plan |
make build # build ./bin/kompensator
make test # run tests
make race # run tests with the race detector (needs a C compiler)
make vet # go vetMIT © kratec GmbH