Docker Compose Converter

COMPOSE DEVELOPER DOCKER

About this tool

Convert a docker run command to docker-compose.yml — handles ports, volumes, env, restart, networks.

Convert a docker run command into the equivalent docker-compose.yml service block. Handles ports, volumes, env, restart, networks, healthcheck.

RT-DEV-073 · Developer Tools

docker run command (multi-line with \ OK)

docker-compose.yml

version: "3.8"

services:
  example:
    image: nginx:alpine
    ports:
      - "8080:80"
    restart: unless-stopped

How to use the Docker Compose converter

Paste your docker run command

Single-line or multi-line with \ continuation — both formats work. The tool tokenises the command, identifies flags, and builds the equivalent compose service.

Review the output

The right pane shows a complete docker-compose.yml with the standard services: block. Volumes and networks declared via shorthand are promoted to top-level volumes: and networks: sections automatically.

Watch for the warnings

Some docker run flags don't map cleanly to compose (e.g. --rm, --init as a flag, certain --cap-add patterns). Anything ambiguous appears in the yellow warnings box with guidance on what to do.

Copy or download

Copy the YAML to your clipboard or download as docker-compose.yml. The output is valid compose v3.8 — bring it to your project root and run docker compose up -d.

Docker Compose — when one container becomes a stack

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.

10 Docker Compose facts every developer should know

Docker Compose was originally called Fig, a separate open-source project acquired by Docker in 2014. The docker compose Go-based rewrite landed in 2021, replacing the legacy docker-compose Python script.

The version: top-level key was deprecated in Compose v2 (Go-rewrite). Modern compose files don't need it — but it's still accepted for backward compatibility.

Service-to-service hostname resolution works automatically — postgres:5432 from the app container resolves to whatever IP the postgres service is on, via Docker's embedded DNS.

Named volumes (volumes: { pgdata: }) persist across docker compose down and up. Anonymous volumes (no name) get garbage-collected on every down.

depends_on alone doesn't wait for a service to be ready — only for it to be started. For real readiness, add condition: service_healthy with a healthcheck: on the dependency.

The env_file: directive loads variables from a .env-style file at runtime. Variables in environment: override env_file values — useful for per-environment overrides.

docker compose up --build rebuilds images defined with a build: directive. Without --build, compose reuses the cached image — a common reason "my code changes aren't showing."

The default project name is the directory name. docker compose -p myproject up overrides this — useful for running multiple instances of the same compose file on one host.

Compose secrets (top-level secrets: block) mount file-based secrets into containers without exposing them in environment variables — better than environment: { DB_PASS: ... } for production.

The profiles: directive lets you mark services as optional. docker compose --profile dev up brings up only services with profile dev — useful for "tools" services like adminer that aren't needed in production.

Frequently asked questions

What docker run flags does the converter handle?

--name, -p / --publish, -v / --volume, -e / --env, --env-file, --restart, --network, --depends-on, --healthcheck-*, --cap-add, --cap-drop, --privileged, --init, --user, --workdir / -w, --hostname / -h, --rm (with a note), the image, and the command after the image.

Yes. The output uses Compose v3.8 syntax, which is supported by both the legacy Python docker-compose tool and the modern Go-based docker compose CLI. We default to v3.8 because it covers 95% of real-world needs.

Named volumes (e.g. -v pgdata:/var/lib/postgresql/data) are added to a top-level volumes: block in addition to the service mount. Bind mounts (e.g. -v ./html:/usr/share/nginx/html) stay as inline service-level mounts only.

YAML quoting is applied automatically when the value contains spaces, colons, or other characters that would break YAML parsing. The tool also escapes quotes inside quoted values.

Not yet — the current version handles one command at a time. For multi-service stacks, run the conversion for each command separately and combine the resulting service blocks into a single services: section.

No exact equivalent. Compose containers stay around after stopping, by design. The closest is to run with docker compose run --rm <service> for one-off commands, but the long-running service definition itself has no --rm setting.

Yes. --health-cmd, --health-interval, --health-timeout, --health-retries, and --health-start-period all map to the healthcheck: block in the service.

If your docker run command uses --network, the named network is added to a top-level networks: block and the service is attached to it. If no network is specified, the service uses compose's automatic default network — which is fine for most cases.

No. All parsing and YAML generation runs in your browser using vanilla JavaScript — no library, no remote call. The command and the generated YAML never leave the page.

Not in this tool. The conversion is lossy in that direction — compose can express things (multi-service dependencies, healthchecks-with-readiness) that don't fit a single docker run command. We may ship a compose-to-docker-run tool in a future update.

Docker Compose Converter