Developer tools · Docker run to Docker compose converter
How docker run flags map to Compose keys: -p, -v, -e, --name and more
· How it works
docker compose developer-workflow
Most docker run flags have a one-to-one Compose equivalent, and a few have none. This post walks through the mapping so a converted service definition reads as expected.
A docker run that wraps three lines in the README — it works, nobody can review it, and the team wants a compose.yaml
A multi-line docker run can start a service today while hiding its operational contract in a shell alias or README. A Compose file moves the same choices into a reviewable service definition, but conversion must account for every flag rather than silently dropping security settings. ToolAcre parses the command as text: it never runs the image, opens a Docker socket or deploys a container. Treat the output as a draft configuration that still needs an operator to check host paths, credentials and network assumptions.
The shape of a service — image, then a set of keys that mirror the flags, under services: and a service name
Compose YAML starts under services:, followed by a service name and image:. Unlike a command line, its keys group repeated values such as ports and environment entries into sequences. ToolAcre derives a service name from --name or the image and builds a model before serializing YAML. Current Compose files do not need a top-level version: key; adding one because an older blog post showed it would create an obsolete warning rather than improve compatibility.
The common flags — -p to ports, -v to volumes, -e to environment, --name to container_name, --restart to restart, --network to networks
Common mappings make the file recognizable: -p 8080:80 becomes ports: with a quoted mapping, -v host:container becomes a volumes entry, -e KEY=value goes into environment, --name becomes container_name, --restart becomes restart and --network needs network context. Quoting the port mapping matters because YAML should treat it as a string, not interpret punctuation as another type. A named volume may require its own top-level volumes declaration; a host bind mount should be checked against the machine where Compose will run.
The less common flags — --hostname, --user, --workdir, --entrypoint, --cap-add, --device, --label, --add-host and their keys
Flags such as --hostname, --user, --workdir, --entrypoint, --cap-add, --device, --label and --add-host have corresponding service concepts, but their semantics may depend on the runtime and host. An unsupported --security-opt must not be invented as a plausible-looking key or discarded invisibly. ToolAcre lists warnings naming unsupported options so a reviewer can finish the mapping manually or decide that Compose is not the right replacement. Presence of a YAML key does not prove that the service starts with the same privileges.
Positional arguments — the image becomes image:, and anything after it becomes command:
The image name is a positional argument after run and its options. Arguments after the image become the service command, not more Docker run flags; moving a token across that boundary changes what program receives it. Shell quotes and backslashes also matter when splitting one README example into tokens. ToolAcre’s parser is not a shell interpreter, so a variable such as $HOME should be reviewed in context rather than assuming it expands as it would in the original interactive shell.
Worked example: converting a Postgres docker run — the full command, the resulting service definition, and a line-by-line comparison
Consider the illustrative command docker run -d --name demo-db -p 5432:5432 -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=demo-only --restart unless-stopped postgres:16. ToolAcre emits services.demo-db with image postgres:16, container_name demo-db, a quoted 5432:5432 port, a pgdata volume, an environment list entry, restart: unless-stopped, and a top-level pgdata volume declaration. It warns that -d is a command-line choice; docker compose up -d handles it. “demo-only” is a deliberately insecure teaching placeholder—never commit a real database password into this generated YAML.
What this does not cover — flags with no service equivalent (-d, --rm) and things not in the command at all, such as build contexts
Not every run flag has a durable service-property counterpart. -d is handled by the compose command you invoke; --rm belongs to a one-off compose run rather than a long-running service. A build context, secret store, health strategy or multi-service dependency absent from the original command cannot be inferred. The tool reports unsupported flags instead of pretending its output is a complete deployment plan. Read the Docker Compose service reference before deploying a privileged or network-sensitive container.
Takeaway: Compose is the same configuration, structured — and the converter produces the service definition from the command you paste
Compose is the same configuration, structured for review and repeatability. Docker run to Docker compose converter gives you a candidate service definition in your browser and keeps the pasted command local; it does not execute Docker. Compare every source flag against its YAML key, address warnings and remove secrets from plain environment blocks before applying the result to a real host.