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.

The version key, and why this converter still writes one

"Compose v2" is two different things, which is most of why this subject is confusing. It is the name of the file format that introduced the version: '2.x' header, and it is also the name of the Go rewrite of the command — the one you invoke as docker compose rather than docker-compose. They are unrelated numbers.

The file-format numbers are the part that has been retired. There is now one document, the Compose Specification, and it is explicit about the header: the top-level version property is defined by the Compose Specification for backward compatibility. It is only informative you'll receive a warning message that it is obsolete if used. It is not used for validation either — Compose doesn't use version to select an exact schema to validate the Compose file, but prefers the most recent schema when it's implemented.

This converter nevertheless emits version: "3.8" as the first line of its output. That is a defect rather than a design choice, and it is recorded as one; until it is fixed, delete that line before you commit the file. Nothing else in the generated YAML depends on it, and removing it silences the obsolescence warning.

What docker run flags don't map to compose

Most map one-to-one, and the exceptions are worth naming. --rm has no service-level equivalent: a Compose service describes something that is meant to exist, so the closest you get is docker compose run --rm <service> for a one-off. --name becomes the service name, which is the name other services resolve over the network; the separate container_name: key sets the literal container name, and the specification warns that it forecloses scaling — Compose does not scale a service beyond one container if the Compose file specifies a container_name. Attempting to do so results in an error. --init and --privileged become the boolean keys init: true and privileged: true, and this converter writes both. --cap-add NET_ADMIN becomes cap_add: [NET_ADMIN]. Flags in the parser's known-argument list that it does not yet translate — --device, --ulimit, --dns, --add-host, --memory, --cpus, --label, --entrypoint — are reported by name rather than dropped, so nothing disappears quietly.

From compose to Kubernetes

kompose, a Kubernetes SIG-Apps project, converts a docker-compose.yml into Deployment and Service manifests. Expect the translation to be lossy in specific, predictable ways: depends_on has no Kubernetes counterpart because pods do not have an ordering primitive, healthchecks map onto liveness and readiness probes that behave differently from Compose's single check, and resource limits use a different syntax entirely. For a small stack it produces a starting point rather than a finished manifest.

Production gotchas worth knowing

Three catch people out. Every service in the file shares one default network, so any container can reach any other by service name — fine in development, not an isolation boundary. Declare named networks and attach services deliberately if you need one. Relative paths resolve against the Compose file, not your shell. The specification says so for env_file — relative path are resolved from the Compose file's parent folder — and warns that an absolute path makes the file non-portable; the same care applies to bind mounts, which is why a named volume is the safer choice for anything that must survive. And short-form depends_on waits for start, not for readiness. The long form is what you want: condition: service_healthy against a dependency that defines a healthcheck:, or service_completed_successfully for a migration container that must finish before the app boots.