JACO documentation

JACO — Just Another Container Orchestrator. Multi-node, Docker-engine, raft-replicated, embedded Caddy, WireGuard mesh, nftables-enforced isolation. Two binaries: jacod (daemon) and jaco (CLI).

This tree is the user-facing documentation.

Start here

Getting started — install on three hosts, form a cluster, ship a deployment, read logs. End-to-end in one page.
Installation — per-distro packages, the generic tarball, verification, on-disk layout.
Configuration — /etc/jaco/jacod.yaml: every key, its default, and what changes when you set it.

CLI reference

Every jaco subcommand has a dedicated page with synopsis, flags, auth, behavior, exit codes, and examples. See cli/README.md for the index and the global flags shared by every command.

Manifests

JACO consumes a pair of files per deployment: your existing docker-compose.yml plus a small jaco.yaml overlay declaring replica counts, placement, and routes.

jaco.yaml schema — closed schema: deployment, services, routes.
Supported compose fields — what JACO honors, ignores, and rejects.
Examples — progressive samples from one service to multi-network with routed ingress.

Concepts

Why each subsystem is shaped the way it is.

Architecture — the two binaries, the verticals, the project status.
Cluster lifecycle — bootstrap, join, leader election, graceful remove.
Networking — WireGuard mesh, per-(deployment, network) bridges, /24 IPAM, DNS.
Isolation — nftables ruleset, cross-deployment DROP, ready gate.
Ingress — embedded Caddy, ACME, HTTP-01 challenge coordination, L4 ports.
Scheduling — placement modes, rolling updates, restart policy.
Auth and tokens — operator tokens, join tokens, the unix-socket trust boundary.
Status and errors — closed enums, replica states, error codes.
Observability — OTel exporter env, span names, metrics, logs.

Operations

Migration — move an existing docker-compose stack (with volumes) onto a JACO cluster.
Upgrades — rolling jaco self-upgrade walkthrough.
Backups — jaco backup and jaco restore end-to-end.
Recovery — quorum loss, node loss, partitions, isolation drift.
Troubleshooting — the error codes you will actually hit and how to clear them.

Contributing

Repository layout — what lives where.
Development — make build/test/vet/lint, proto generation, working with internal/.
Release and packaging — how releases are cut, signed, and published.
Testing — unit, integration, the privileged isolation rig, and the comparative samples bench.
Architecture decision records — load-bearing design decisions for multi-PR efforts (pressure-based scheduling, orchestrator benchmark).

JACO is licensed under the Apache License 2.0. Attribution notices for bundled dependencies are in NOTICE, and the full per-module third-party inventory (generated from go.mod) is in THIRD_PARTY_LICENSES.md.