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 11

depends_on: Why Compose Still Starts Wrong

depends_on orders container starts, not readiness — Postgres can still be mid-recovery seconds after its container 'started'. Real log timestamps proving the gap, plus the condition: service_healthy fix that closes it.

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?

Part 17

Docker Compose: env_file vs environment

You edit .env, restart the container, and the old value is still there - no error anywhere. The exact precedence order between env_file, environment, and your shell, reproduced on a real stack, plus the fix when Compose won't pick up the change.

Part 18

Docker Compose YAML File Explained

Duplicate keys, mixed env syntax, unquoted booleans - none of them throw an error. A structural walkthrough of docker-compose.yml with YAML anchors to cut repetition and the docker compose config habit that catches mistakes before they reach a running container.

Part 19

Docker Compose Commands Cheat Sheet

A README lists 40-plus Docker Compose subcommands. In practice, running several stacks on one homelab host means using about eight of them daily, plus one gotcha: pull, logs, restart, and exec all scope to a single service if you name one.