Docker Compose Converter

docker run is fantastic for "give me one container, now." It runs nginx in front of a static site, spins up postgres for testing, or boots a quick redis for a benchmark. It stops being adequate the moment your application needs multiple services that need to know about each other. The classic three-tier — a web app, a database, a cache — is three docker run commands you have to remember to run in the right order, with manually-typed network names so the services can find each other, and manually-managed restart-on-reboot scripts so the whole thing comes back up after a server reboot. Docker Compose collapses all of that into one YAML file plus one command.

The compose YAML you actually need

A useful docker-compose.yml has three top-level keys: services: (the containers themselves), volumes: (named persistent storage), and networks: (custom bridge networks for service-to-service communication). Inside each service: image: (which image to run), ports: (host:container port mappings), environment: (env vars), volumes: (mounts), restart: (policy), and depends_on: (startup ordering). That's it for 90% of real-world usage. The tool above translates a single docker run into exactly this minimal-but-complete structure.

Compose v2 vs v3 — does it matter?

Compose has had a confusing version history. The original Compose v1 used a flat YAML without a version header. Compose v2 (~2017) added the version: '2.x' header and feature dependencies. Compose v3 (~2018) added swarm-mode features (replicas, deploy directives) at the cost of some v2 features (the ability to bind a service to a specific container ID, certain network options). Docker Compose v2 — the rewritten Go-based docker compose command introduced in 2021 — supports both. For pure single-host use, version 3.8 is the safest default; this tool generates that. For genuine swarm/Kubernetes work, you're past the point where this converter helps.

What docker run flags don't map to compose

A few flags translate awkwardly. --rm (auto-remove on exit) has no compose equivalent — compose containers stay around for inspection by default. --name becomes the service name itself in compose; you can also set container_name: for the literal docker container name, though it conflicts with scale. --init works the same. --device requires the devices: list inside the service. --cap-add NET_ADMIN works the same via cap_add: [NET_ADMIN]. The tool above maps all the common cases and surfaces a warning for anything it isn't confident about.

From compose to Kubernetes

The natural progression: compose for development, Kubernetes for production. Tools like kompose (from the Kubernetes project) generate Kubernetes Deployment + Service manifests directly from a docker-compose.yml. The translation is lossy — compose's depends_on doesn't have a perfect Kubernetes equivalent, healthchecks behave differently, and resource limits use different syntax. But for a basic 3-service stack, kompose convert on the compose file generated by this tool produces a usable starting point for a Kubernetes deployment. We will ship a separate kompose-style tool in a future update.

Production gotchas worth knowing

Three things bite first-time compose users in production. First, the implicit default bridge network is shared across all services in the file — explicit named networks give you per-service isolation. Second, volumes: ./data:/data is host-relative which breaks when you run the same compose file from a different working directory; absolute paths or named volumes are safer for non-dev use. Third, compose's startup ordering via depends_on only waits for the container to start, not for the service inside to be ready — pair it with a healthcheck: block.