Back then, Kubernetes didn’t exist yet. Options for running multiple services on a single machine came down to bash scripting, hand-written Nginx configs, and a lot of coffee. Tutorials on “homelab for humans” were nowhere to be found.

This tutorial is what I wish I had found back then. It’s been running for several years now. Not without evolving: services added, others dropped, choices revisited. But the foundation is there, stable — and that’s what success looks like in self-hosting.

The setup: ten self-hosted web services on a local machine, accessible from a browser via readable URLs, without touching DNS configuration, without renting a VPS, without managing TLS certificates. The ingredient that makes it possible: sslip.io , a public DNS service that encodes the IP directly in the domain name. service.192.168.1.10.sslip.io resolves to 192.168.1.10, with zero configuration, from any machine on the local network.

This tutorial is aimed at someone who knows Docker but is starting from scratch on self-hosted service orchestration.

Table of contents

1. Philosophy and architecture choices
2. The building blocks
3. Step-by-step setup
4. Adding a new service
5. Patterns and conventions
6. Common pitfalls
7. Conclusion
8. References

1. Philosophy and architecture choices

Goal

Run multiple web services on a local machine, accessible from a browser via readable URLs, without touching DNS configuration, without renting a VPS, without managing TLS certificates.

Why Docker Compose and not something else?

Docker Compose is the right level of complexity for a personal homelab. Kubernetes is too heavy for a single machine. Docker Swarm is in decline. Compose is simple, readable, versionable, and sufficient for dozens of services.

Why Traefik and not Nginx Proxy Manager?

Nginx Proxy Manager (NPM) is a graphical interface for configuring Nginx as a reverse proxy. Routes are stored in a database and configured through a UI.

Traefik automatically reads Docker container labels and generates its configuration on the fly. When a container starts with the right labels, Traefik discovers it and creates the route immediately, without restarting, without opening any UI.

This “configuration as code” approach has two major advantages:

• A service’s configuration lives in its compose.yaml, in the same place as everything else.
• Adding a service requires no changes to Traefik.

Why Dockge and not Portainer?

Portainer is a full Docker management tool: images, volumes, networks, individual containers… powerful but complex.

Dockge is focused on a single thing: managing Docker Compose stacks. Its UI is minimal and intuitive. For a homelab where everything is managed through Compose, it’s sufficient and much more pleasant to use.

Why sslip.io?

Web services need a hostname (e.g. dozzle.myserver.local) for Traefik to route correctly. The usual options:

• Edit /etc/hosts on every machine: tedious, not shareable.
• Set up a local DNS server (Pi-hole, AdGuard): requires additional infrastructure.
• Buy a domain and configure DNS: costs money and time.

sslip.io is a public DNS service that automatically resolves <anything>.<IP>.sslip.io to <IP>. Example: dozzle.192.168.1.10.sslip.io resolves to 192.168.1.10. Nothing to configure — the DNS works everywhere without touching anything.

2. The building blocks

The shared Docker network

All services and Traefik must share the same Docker network so Traefik can communicate with them. This network is called traefik and is created once:

docker network create traefik

It is an external network (created outside any Compose file). Each compose.yaml declares it as external:

networks:
    traefik:
        external: true

Why external rather than internal to a Compose file? Because multiple independent stacks all need to connect to it. A network internal to a Compose file is only accessible to services within that file.

Traefik: the reverse proxy

Traefik listens on port 80 and routes HTTP requests to the right container based on the Host header.

Its main configuration lives in stacks/traefik/docker/traefik/traefik.yaml:

api:
    dashboard: true
    insecure: true

entryPoints:
    web:
        address: :80
    ping:
        address: :8082

providers:
    docker:
        endpoint: unix:///var/run/docker.sock
        exposedByDefault: false

log:
    level: INFO

global:
    sendAnonymousUsage: false

exposedByDefault: false is important: Traefik ignores all containers by default. A container must explicitly opt in with the label traefik.enable: true. This prevents accidentally exposing services.

The ping entrypoint on port 8082 is dedicated to health checks. Separating it from the web entrypoint prevents health check requests from appearing in access logs.

To access the Docker daemon, Traefik mounts the socket:

volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Dockge: the stack manager

Dockge runs inside a container itself (the compose.yaml at the root of the repo). It needs two things:

1. Access to the Docker socket to manage the other containers.
2. Access to the stack directories to read and edit compose.yaml files.

The critical point is the stack mount. Dockge launches stacks by passing absolute paths to the Docker daemon. These paths must be identical inside the Dockge container and on the host. The solution:

volumes:
    - ${PWD}/stacks:${PWD}/stacks
environment:
    DOCKGE_STACKS_DIR: ${PWD}/stacks

${PWD} is a shell variable resolved at docker compose up time. It equals the current directory. If Dockge is launched from /home/user/homelab, the stacks folder will be mounted at /home/user/homelab/stacks on both sides. This is the only way to prevent Docker from creating ghost directories in the wrong place.

Practical consequence: always run docker compose up -d from the root of the repo.

Dockge’s persistent data (configuration, history) lives in a named volume created in advance:

docker volume create homelab_dockge_data

A named volume survives docker compose down -v. An anonymous volume would be destroyed with the stack.

3. Step-by-step setup

Step 1: clone and configure

git clone <repo> homelab
cd homelab

Find the machine’s local IP:

hostname -I | awk '{print $1}'
# e.g.: 192.168.1.10

Create and edit the root .env:

cp .env.example .env
# Edit .env:
# IP=192.168.1.10
# DOMAIN=sslip.io
# COMPOSE_PROJECT_NAME=dockge  ← important, see conventions section

Step 2: Docker prerequisites

docker network create traefik
docker volume create homelab_dockge_data

Step 3: start Dockge

echo "STACKS_DIR=$(pwd)/stacks" >> .env
docker compose up -d

Dockge is accessible at http://<IP>:5001. It is exposed directly on port 5001, not through Traefik (Traefik is not running yet at this point). Create an admin account on first launch.

Step 4: configure the stacks

For each directory in stacks/, copy the .env.example:

for stack in stacks/*/; do
    cp "${stack}.env.example" "${stack}.env"
done

Then edit each .env to set IP and DOMAIN to the same values as in step 1. The COMPOSE_PROJECT_NAME value is pre-filled with the folder name — do not change it (see conventions section).

For filebrowser, also set FILEBROWSER_ROOT to the local path to expose.

Step 5: start the stacks from Dockge

From the Dockge interface (http://<IP>:5001), in this order:

1. Traefik first

Traefik must be running before the other services. Without Traefik, routes don’t exist and services are unreachable via their URL.

After starting, verify Traefik is healthy:

docker ps --filter name=traefik

2. The other stacks in any order

Each stack automatically registers itself with Traefik via its Docker labels. Traefik discovers new containers in real time.

3. Homepage last

Homepage reads Docker labels from all running containers at startup to build the dashboard. Starting it last ensures it discovers all active services from the first launch.

4. Adding a new service

Here is the compose.yaml template for any new service:

services:
    myservice:
        image: vendor/myservice:latest
        restart: unless-stopped
        healthcheck:
            test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:<PORT>/ || exit 1"]
            interval: 30s
            timeout: 10s
            retries: 3
            start_period: 10s
        labels:
            # Homepage - auto-discovery in dashboard
            homepage.group: tools
            homepage.name: My Service
            homepage.icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/myservice.webp
            homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

            # Traefik - HTTP routing
            traefik.enable: true
            traefik.http.routers.myservice.entrypoints: web
            traefik.http.routers.myservice.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
            traefik.http.services.myservice.loadbalancer.server.port: <PORT>
        networks:
            - traefik

networks:
    traefik:
        external: true

And the associated .env.example:

COMPOSE_PROJECT_NAME=myservice
IP=127.0.0.1
DOMAIN=sslip.io

The folder name determines the subdomain. If the folder is called myservice, the service will be accessible at myservice.<IP>.<DOMAIN>. That’s it.

To find services worth adding, selfh.st is an excellent resource: it’s a catalog of self-hosted software organized by category (media, security, productivity, monitoring…), with a description, screenshot, and GitHub link for each. The site also publishes a weekly newsletter on new releases.

Checklist for a new service

• Create stacks/<subdomain-name>/compose.yaml
• Create stacks/<subdomain-name>/.env.example with COMPOSE_PROJECT_NAME=<name>
• Copy .env.example to .env and fill in IP/DOMAIN
• Check the port in the Traefik labels
• Choose the Homepage group: infra, monitoring, tools
• Find the icon on selfhst/icons
• Add persistent data in a volume if needed
• Start from Dockge and verify the container is healthy

5. Patterns and conventions

The ${COMPOSE_PROJECT_NAME} variable

Docker Compose automatically sets COMPOSE_PROJECT_NAME to the stack folder name. We use it to build URLs dynamically:

traefik.http.routers.dozzle.rule: Host(`${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}`)
homepage.href: http://${COMPOSE_PROJECT_NAME}.${IP}.${DOMAIN}

Advantage: no *_HOST variable to maintain in each .env. Renaming the folder automatically changes the subdomain.

Warning: in the .env, COMPOSE_PROJECT_NAME must be defined explicitly with the stack folder name. Without it, Docker Compose uses the current directory name at launch time, which can produce unexpected values depending on where the command is run from.

Homepage groups

Services are organized into three groups in the dashboard:

This grouping is specific to this homelab, not an enforced convention. Homepage accepts any value for homepage.group: you can create as many groups as needed and name them however you like (media, home-automation, dev…). The dashboard reorganizes automatically.

Health checks

All services have a health check. This is crucial because Traefik silently ignores unhealthy containers: a service with a failing health check will not appear in routing, even with traefik.enable: true.

Three edge cases encountered in practice:

1. localhost does not always resolve to 127.0.0.1

In some minimal images, localhost is not resolved. Use 127.0.0.1 explicitly:

test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/ || exit 1"]

2. Images without a shell (scratch-based)

Images based on scratch (e.g. Dozzle) do not contain /bin/sh. CMD-SHELL fails. Use the embedded binary:

test: ["CMD", "/dozzle", "healthcheck"]

3. Images without wget or curl

Some Node.js or JVM images have neither wget nor curl. Possible solutions:

• If Node.js is available: node -e "require('http').get('http://localhost:PORT', r => process.exit(r.statusCode < 400 ? 0 : 1)).on('error', () => process.exit(1))"
• If curl is available: curl -fs http://127.0.0.1:PORT/
• If the app binary exposes a healthcheck subcommand: use it directly.

Data persistence

For services that have data (configuration, user accounts, database):

volumes:
    - ./docker/data:/path/in/container

The ./docker/ folder lives inside the stack directory and can be versioned, except for runtime data which goes in .gitignore.

Rule: add stacks/<service>/docker/ to .gitignore if the folder contains data that should not be committed (SQLite databases, uploads…).

Traefik label conventions

By convention, the name used in Traefik labels (traefik.http.routers.<name>) matches the Docker service name in compose.yaml. In practice, align it with the folder name:

stacks/it-tools/    →    service: ittools    →    traefik.http.routers.ittools.*

This is not a technical constraint from Traefik, just a readability convention.

6. Common pitfalls

Dockge: Stop then Start, not Restart

When a compose.yaml is modified from an IDE and the changes need to be applied, use Stop + Start from Dockge, not “Restart”. Restart restarts the existing container without re-reading the compose.yaml. Stop + Start recreates the container with the new configuration.

Modified labels: restart Homepage

Homepage reads Docker labels at startup. If homepage.group or homepage.name is changed for a service, Homepage won’t see it until it is restarted.

Container starts but is not routable

Check in order:

1. docker ps: is the container healthy? Traefik ignores unhealthy containers.
2. Is the container on the traefik network?

docker inspect <container> --format '{{json .NetworkSettings.Networks}}'

3. Is the label traefik.enable: true present?
4. Does the Host(...) rule match the URL being tested?

Mounting non-existent files under Docker Desktop / WSL

When Docker Desktop (WSL) mounts a file that does not yet exist on the host, it creates a directory instead. This ghost directory then blocks the mount of the actual file. Symptom: the container fails to start with a mount error.

Solution: ensure the file exists on the host before starting the container, or use a directory mount instead of a file mount.

Watchtower: Docker API too old

On some configurations, Watchtower tries to communicate with the daemon starting the negotiation at API v1.25 (its historical minimum). Recent versions of Docker reject this version. Symptom: the container restarts in a loop with client version 1.25 is too old. Minimum supported API version is 1.40.

Fix in the Watchtower compose.yaml:

environment:
    DOCKER_API_VERSION: "1.40"

1.40 is the value to use, regardless of your Docker version. It is not your exact version — it is the minimum the daemon accepts, as stated in the error message. To check the actual API version of your daemon:

docker version --format '{{.Server.APIVersion}}'

${PWD} in Dockge’s compose file

${PWD} is not a .env variable — it is a shell variable resolved at docker compose up time. It equals the current terminal directory. Running docker compose up -d from any other directory will produce a wrong value and break stack volume mounts.

This homelab is designed to run on a Linux machine or WSL. All commands have been tested on Ubuntu/WSL2 with Docker Desktop.

Conclusion

I’m well aware this tutorial doesn’t cover everything. We could have added authentication in front of each service, run the whole thing over HTTPS, set up a socket proxy to limit the Docker daemon’s exposure, or pinned precise image versions. But each of those points would have considerably lengthened the article and the complexity of the setup. The goal was to start with something functional and maintainable, not to build a fortress on day one.

The perfect homelab doesn’t exist. The one that runs, does.

guillaumedelre/homelab

Docker Compose homelab with Traefik — independent stacks, auto-configured dashboard, and zero DNS configuration using sslip.io.

References

Then you migrate to the cloud. The institutional knowledge doesn’t follow. The SSH access is gone or inconvenient. And for the first time, you’re staring at fourteen FrankenPHP containers with no idea what they’re actually doing.

That’s the moment you need metrics. Not eventually. Before the migration is done.

The problem with doing it properly

The correct way to instrument a PHP service for Prometheus: add a client library, write counters and histograms around what you care about, expose a /metrics route, update the scrape config. For one service, that’s a reasonable afternoon. For fourteen services mid-migration, it’s a multi-sprint project that competes with everything else that needs to move.

The calculation is awkward. You need metrics to trust that the migration is going well. But adding metrics to everything before the migration means the migration takes longer. And the longer it takes, the more you need metrics to know where you stand.

Something had to give.

What FrankenPHP carries without announcing it

FrankenPHP is not a PHP runtime that happens to use Caddy as its web server. The relationship is inverted: Caddy is the server, and PHP is a Caddy module. Every HTTP request flows through Caddy before it reaches application code.

Caddy ships with a Prometheus-compatible metrics endpoint built in. No plugin, no extra binary. Enable the admin API and it’s there.

CADDY_GLOBAL_OPTIONS is a FrankenPHP environment variable that injects directives directly into Caddy’s global configuration block. Two lines are enough:

environment:
    CADDY_GLOBAL_OPTIONS: |
        admin 0.0.0.0:2019
        metrics

admin 0.0.0.0:2019 binds the admin API to all network interfaces - the default is localhost-only, which is unreachable from a Prometheus container on the same network. metrics enables the endpoint.

After that, every container responds to GET :2019/metrics with a full Prometheus payload. Request counts labeled by status code, latency histograms, active connections. No route added to the application. No composer require. No Dockerfile change.

One environment variable, added to each service definition in a single commit. Fourteen scrape targets, all producing data.

A usable picture in Grafana

The Prometheus scrape config lists every service by its container name:

scrape_configs:
    - job_name: caddy
      metrics_path: /metrics
      static_configs:
          - targets:
              - authentication:2019
              - content:2019
              - media:2019
              # all 14 services

Grafana sits on top of Prometheus. The Caddy community dashboard gives you request rates, error rates, and latency percentiles per service, per endpoint, per status code. Within a day of the migration landing in the new environment, there was something meaningful to look at.

The data tier follows the same logic: exporters for PostgreSQL, Redis, and RabbitMQ scrape at the infrastructure level without touching application code. Community dashboards exist for all of them.

What this baseline actually covers

The HTTP metrics from Caddy are web server metrics, not application metrics. They answer: is this service receiving traffic, is it returning errors, how fast is it responding. The kind of questions you ask when something is broken and you need to triage in the dark.

They don’t answer: how many items were processed today, which background job is stuck, what is the business impact of this latency spike. For those you need application instrumentation, and that work still exists when you have specific things to measure.

But in a migration context, that distinction matters less than it sounds. The things that break during a cloud migration are mostly infrastructure problems: a service that can’t reach its database, a memory limit that was set too low, a queue consumer that stopped picking up messages. Those are exactly the things the baseline covers.

Getting instrumentation right for business-level events can wait until the platform is stable. Getting enough visibility to know whether the migration succeeded cannot.

Then in March 2025, Let’s Encrypt revoked the certificate. The wildcard cert for traefik.me is gone and it’s not coming back.

What traefik.me was actually selling

traefik.me is a wildcard DNS resolver. Type anything.traefik.me and it resolves to 127.0.0.1. Type anything.10.0.0.1.traefik.me and it resolves to 10.0.0.1. No account, no configuration, no infrastructure to maintain. The DNS part still works fine, by the way.

The certificate was the bonus: a wildcard cert for *.traefik.me that pyrou, the maintainer, generated with Let’s Encrypt and distributed at https://traefik.me/cert.pem and https://traefik.me/privkey.pem. It was convenient precisely because it was shared: download, drop into Traefik, done.

Sharing a private key is why it died.

The CA/Browser Forum Baseline Requirements, section 9.6.3, require subscribers to “maintain sole control” over their private key. Distributing it to anyone who visits a URL is the exact opposite of sole control. Let’s Encrypt sent a notice, blocked future issuance for the domain, and revoked the existing certificate. Pyrou confirmed the situation and recommended mkcert as an alternative. The project will live on as a DNS resolver only.

The cert had already been revoked twice before 2025. Third time was the last.

sslip.io does the same thing, differently

sslip.io is also a wildcard DNS resolver, with one difference: the IP is encoded in the hostname rather than resolved from a fallback. 10-0-0-1.sslip.io resolves to 10.0.0.1. myapp.192-168-1-10.sslip.io resolves to 192.168.1.10. IPv6 works too.

The infrastructure behind sslip.io is also more visible: three nameservers in Singapore, the US, and Poland, handling over 10,000 requests per second, with public monitoring. About 1,000 GitHub stars and active maintenance under the Apache 2.0 licence.

Strip away the certificate story and the comparison is pretty straightforward:

traefik.me’s only remaining advantage is the 127.0.0.1 fallback: URLs without an IP segment. That matters if you really want myapp.traefik.me instead of myapp.127-0-0-1.sslip.io. Whether that difference is worth the infrastructure uncertainty is a short conversation.

mkcert fills the gap

mkcert creates a local certificate authority, installs it in the system trust store and whatever browsers it finds, then issues certificates signed by that CA. Browsers see a trusted chain. No warning, no click-through, no “proceed anyway”.

mkcert -install

That’s the one-time setup. After that, generating a certificate is one command:

mkcert "*.127-0-0-1.sslip.io"
# produces _wildcard.127-0-0-1.sslip.io.pem
#          _wildcard.127-0-0-1.sslip.io-key.pem

The limitation is that mkcert’s CA is local. Other machines on the network won’t trust it by default. For a solo dev setup that’s fine. For a shared team environment, you’d need to distribute the CA root, which is essentially the same operational problem traefik.me was trying to avoid, just smaller in scope.

The Traefik configuration

The setup is the same regardless of which DNS service you pick. Traefik needs the certificate mounted as a volume and a static file provider pointing at a TLS configuration file.

# traefik/config/tls.yml
tls:
  certificates:
    - certFile: /certs/cert.pem
      keyFile: /certs/key.pem
  stores:
    default:
      defaultCertificate:
        certFile: /certs/cert.pem
        keyFile: /certs/key.pem

The key practice: run Traefik in its own Compose project, separate from the services it routes to. Each service project connects to Traefik through a shared external network. Start and stop services independently without touching the reverse proxy.

Start by creating the external network once:

docker network create traefik-public

traefik/compose.yml - Traefik alone, owning the network:

services:
  traefik:
    image: traefik:v3
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/etc/traefik/config
      - ./certs:/certs
    command:
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --providers.docker=true
      - --providers.docker.network=traefik-public
      - --providers.file.directory=/etc/traefik/config
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

Copy the mkcert output into ./certs/, rename to cert.pem and key.pem, then:

docker compose -f traefik/compose.yml up -d

Traefik is up, listening on 80 and 443, watching Docker for new containers. Nothing is routed yet.

whoami/compose.yml - a service that joins the same network:

services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.127-0-0-1.sslip.io`)"
      - "traefik.http.routers.whoami.tls=true"
      - "traefik.http.routers.whoami.entrypoints=websecure"
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

docker compose -f whoami/compose.yml up -d

Traefik detects the new container via the Docker provider, reads its labels, and adds the route. https://whoami.127-0-0-1.sslip.io responds immediately. Bring whoami down and the route disappears. Traefik keeps running without noticing.

The external: true declaration is the load-bearing line. Without it, Compose creates a project-scoped network: Traefik and whoami end up on different networks and can’t reach each other, even though both are running. The external network is the shared bus every service project must explicitly opt into.

If you prefer traefik.me URLs, replace the mkcert command and the host label:

mkcert "*.traefik.me"

- "traefik.http.routers.whoami.rule=Host(`whoami.traefik.me`)"

The DNS fallback to 127.0.0.1 handles the rest.

What the traefik.me story actually teaches

The certificate distribution model was always fragile. A “public-private key pair” is a contradiction in terms. Every revocation was a warning that the next one could be permanent. Eventually it was.

The lesson isn’t specific to traefik.me. Any service that provides convenience by quietly removing a security boundary will eventually hit that boundary. mkcert is the right tool for this problem because it operates entirely within your own trust domain: you generate the CA, you install it, you issue the certificates. Nothing depends on a third party’s continued willingness to bend certificate issuance rules.

sslip.io solves the DNS part cleanly. mkcert solves the TLS part cleanly. They compose well. The traefik.me setup was simpler, for a while. Until it wasn’t.

The Vagrant years

The setup made sense at the time. One VM per project, provisioned with shell scripts or Ansible, shared via a versioned Vagrantfile. Onboarding was theoretically vagrant up and you’re done.

In practice, it was vagrant up, wait four minutes, watch the provision fail on a package that changed its download URL, fix it, reprovision, wait again. Vagrantfiles accumulated configuration over time: workarounds for specific machines, OS version pinning, memory tweaks for the team member whose laptop had 8GB. The files became historical documents nobody wanted to touch.

The VM itself was the other problem. Booting took time. Running took memory and CPU that could have gone to the application. File syncing between host and guest added latency that made PHP apps feel slower than they had any right to be. The overhead was significant for what was ultimately just “run a web server.”

We lived with it because everyone did. Vagrant was the standard for local PHP development, and the alternative (each developer managing their own LAMP stack) was clearly worse.

The project that changed the model

The shift wasn’t a decision we made. It was a project that arrived already containerized.

A new client project had a docker-compose.yml at the root, a Dockerfile, and a README that said docker compose up. We ran it. The containers started in seconds. PHP-FPM, nginx, PostgreSQL, Redis: all running, all networked, no provisioning step. Stop the containers, start them again, same state.

The contrast with our Vagrant setup was immediate. Not faster by a percentage: faster by a different order. And the Compose file was actually readable: each service, its image, its volumes, its environment variables, its dependencies. Compared to a provision script that SSHed into a VM and ran apt-get, this was legible.

We migrated everything. Not gradually, all at once, over a sprint. Every project got a docker-compose.yml. Every Vagrantfile was deleted. The transition was the most painful three weeks of infrastructure work I remember, and also the most clearly worth it.

What docker-compose actually changed

Beyond the speed, Compose changed the mental model. Vagrant abstracted a machine. Compose abstracted a set of processes. The distinction matters: with Compose, you can stop the database without stopping the application server, scale a worker service independently, swap the PostgreSQL image for a newer version without touching anything else.

The services declaration also replaced the VM provisioning problem entirely. If a new developer joins, they don’t run a provision script that may or may not work on their OS version. They run docker compose up and get the exact same images everyone else runs.

CI/CD got simpler too. The same docker-compose.yml that ran locally could run in the pipeline. The environment parity that Vagrant promised but rarely delivered was actually real with Compose.

The quiet deprecation

For years, the command was docker-compose: a separate binary, installed independently from Docker itself, written in Python, versioned independently. We used it, it worked, nobody thought much about it.

At some point a colleague mentioned that Docker had integrated Compose directly into the docker CLI. The new command was docker compose, no hyphen, Go rewrite, bundled with Docker Desktop. The old docker-compose binary was deprecated.

We had been using v1 for two years after v2 shipped. Our CI scripts, our Makefiles, our documentation all said docker-compose. Nothing had broken because Docker maintained the old binary for a long time. But the ecosystem had moved on quietly, and we’d missed it.

The migration was trivial: a hyphen removed from every script, a few aliases updated. The lesson was less trivial. Infrastructure tooling evolves without ceremony. The announcement happened, the blog posts were written, the deprecation notices were there. We just weren’t paying attention.

The actual retrospective

Looking back across Vagrant → docker-compose → docker compose, the pattern is less about the tools and more about the defaults.

Vagrant defaulted to “it works on my VM.” The overhead of sharing that VM was permanent.

Compose defaulted to “it works in these containers.” The images are the artifacts; the host machine is irrelevant.

The hyphen between docker and compose was always cosmetic. What mattered was the shift from provisioned machines to declarative services. That shift happened the day we ran a project someone else containerized and realized we never wanted to go back.