Series

Docker Compose for Self-Hosting

The practical guide to running real self-hosted services with Docker Compose — restart policies, networking, volumes and backups, secrets, build vs pull, debugging, and the down/stop/kill difference — grounded in the author's own homelab compose files.

Part 1

Docker Compose Restart Policies Explained

The power blipped, the host rebooted, and half the homelab stack came back up on its own — the other half just sat there, exited. Every container had a restart: line; they weren't all the same line.

Part 2

Docker Compose Networking Explained

Two containers on the same host could reach each other, and neither one was supposed to. Both had landed on Docker Compose's default bridge network — a network that doesn't ask permission before connecting things.

Part 3

Docker Compose Volumes and Backups Explained

I ran docker compose down -v to force a clean restart, out of muscle memory from a different project where that flag was harmless. It wasn't harmless here — it deleted a named volume along with the containers.

Part 4

Docker Compose Secrets vs .env Files

I pasted a fresh Postgres password straight into environment: on a new compose file, then stopped with my cursor over git add . That password was about to sit in plain text in a repo I push to self-hosted Gitea, not because I was careless, but because environment: is the path of least resistance.

Part 5

Docker Compose Build vs Pull vs --no-cache

I edited a Dockerfile, ran docker compose up -d, and the container came back up running the exact same code it had before. No error, no warning, just silence, and a service that looked started but was not the one I had just changed.

Part 6

Debugging a Broken Docker Compose Stack

A fixed triage order for a Docker Compose service that won't start: docker compose ps, logs --tail, the exit code, and the healthcheck status -- in that order, before restarting anything, plus how to tell a real crash loop from a slow first boot.

Part 7

Docker Compose Down vs Stop vs Kill

I ran docker compose stop expecting the stack to fully disappear. A few seconds later, docker compose ps still listed every container and the default network was still there, nothing had been removed, just stopped.

Part 8

Docker Compose for Self-Hosting: The Guide

Restart policy, networking, volumes, secrets, build vs pull, logs, and teardown — the seven decisions a self-hosted Docker Compose stack forces, mapped in one guide with a real annotated compose.yaml and links to a deep dive on each.

Part 9

Docker Compose vs Kubernetes: When to Move

The real decision framework for outgrowing Docker Compose: numeric container and node thresholds, the K3s middle step most guides skip, and what migrating actually costs — grounded in a single-host homelab.

Part 10

Docker Compose Ports Explained

Every Compose stack you copy from a README defaults to the same handful of ports. Here is how host vs container ports actually work, why multi-stack homelabs collide, and when to add a reverse proxy instead of publishing ports directly.

Part 12

network_mode: host in Docker Compose Explained

Home Assistant or Pi-hole goes into a docker-compose.yml, the stack comes up healthy, and device discovery still doesn't work -- no new devices show up. The forum fix is network_mode: host. What it actually does, when it's worth the isolation you give up, and when bridge is still right.

Part 13

Docker Compose Healthchecks Explained

Compose's 'Up' status only means a process started. Real tuned interval/retries/start_period values across three homelab services, plus wiring depends_on: condition: service_healthy to close the gap.

Part 14

Docker Compose Profiles Explained

Docker Compose profiles let one compose.yml split services into groups (core, monitoring, backup, dev) that only start when requested, instead of every service always starting together.

Part 15

Docker Compose: Command Not Found, Fixed

You ran docker-compose up -d on a box where that exact command has worked a dozen times before - or a Pi you just flashed, or a Synology you just rebooted - and the shell answers docker-compose: command not found. Docker itself is clearly installed; docker ps works fine. So what broke?