Side reading
Compose, Swarm or Kubernetes
Why this book uses Docker Compose on one machine, what the alternatives buy you, and the honest signs that you have outgrown it.
This book runs containers with Docker Compose on a single machine. That is a choice, and people who have met Kubernetes at work reasonably ask why.
Here is the reasoning, including the parts that argue against it.
What each one is actually for #
Docker Compose describes a set of containers on one machine in one file. It does not schedule, it does not fail over, it does not move anything anywhere. It reads your file and makes the machine match it.
Docker Swarm is clustering built into Docker. Several machines, services with a replica count, an overlay network, rolling updates. Its great virtue is that it is nearly the same vocabulary as Compose. Its problem is momentum: it works, it is maintained, and almost nobody is building anything new on it, so you are increasingly on your own for anything unusual.
Kubernetes is a control loop for a fleet. You declare intent, controllers reconcile reality towards it, and an enormous ecosystem plugs into that. k3s, k0s and MicroK8s are packagings that make it plausible on small hardware: k3s in particular runs on a single node and is genuinely light.
Podman with quadlets is worth knowing about too: containers as systemd units, no daemon, rootless by default. If "the Docker socket is root" bothers you more than it bothers this book, that is the direction to look.
Why one machine changes the answer #
Most of what an orchestrator gives you is about having more than one machine.
Rescheduling a workload when a node dies is the headline feature, and on a single node there is nowhere to reschedule to. Rolling updates across replicas assume replicas. Overlay networking solves a problem you do not have when everything is on one host. Horizontal autoscaling is not a home server concern.
What remains, when you strip out the multi-node parts, is: declarative configuration, restart on failure, health checks, resource limits, and secret handling. Compose does all of those. Not as thoroughly, but the gap on one machine is small.
And the costs are not small. Kubernetes brings its own networking, its own storage abstraction, its own certificate rotation, its own upgrade path, and a control plane that consumes real memory before you have run anything. When something breaks at 11pm, you are debugging your photo library and a distributed system.
The failure mode is not learning, it is stalling
The strongest argument for Kubernetes at home is that you want to learn Kubernetes. That is a completely legitimate reason, and if it is yours, do it.
Just be honest about which project you are doing. "Set up a home server for my family" and "learn Kubernetes" are both good projects. Doing them as one project is how people end up nine months in with a cluster and no photos on it.
The signs you have outgrown Compose #
Not opinions, symptoms. Any two of these and the question is a real one:
- You have a second machine and you are copying compose files between them by hand.
- You genuinely cannot tolerate downtime for some service, which usually means somebody outside your household depends on it.
- You are writing scripts around
docker composeto sequence things it will not sequence, and those scripts have grown conditionals. - You want a change to be reviewed, applied and rolled back automatically from a repository, and you are building that pipeline yourself.
- You are running enough distinct workloads that scheduling them by hand across resources has become a thing you think about.
None of those describes a first home server. Several of them might describe your third.
If you do move #
Two things worth knowing before you start.
The path is not symmetric. Compose to Kubernetes is a rewrite, whatever the conversion tools claim: the abstractions do not line up, and volumes and networking in particular need rethinking rather than translating. Compose to Swarm is much closer, because it is largely the same file with a deploy: section, which is exactly why Swarm remains attractive for a second machine.
Your data does not move itself. Every chapter in this book that talks about where files live applies unchanged. An orchestrator changes how containers are started, not what a stateful application needs from its storage. Get that part right first, on the simple thing, and it transfers.
What this book does instead #
Compose, on one machine, with the parts that actually matter made explicit: pinned digests, resource limits, restart policies, separate networks per application, and no service published wider than it needs to be.
If you later move to something bigger, none of that is wasted. The reasoning transfers even when the syntax does not.