How to convert docker run to docker compose
A docker run command and a compose service describe the same container in two ways. The image and the command stay as they are. Each option becomes a key under the service: -p becomes ports, -v becomes volumes, -e becomes environment and --restart becomes restart. The docker run to docker compose conversion is mostly this mapping, plus a few details that depend on the option.
docker run -d --name web --restart unless-stopped -p 8080:80 -v ./html:/usr/share/nginx/html:ro nginx:1.27
services:
web:
image: nginx:1.27
container_name: web
restart: unless-stopped
ports:
- "8080:80"
volumes:
- ./html:/usr/share/nginx/html:roThe -d flag disappears because Compose starts services in the background when you run docker compose up -d. The conversion runs in your browser, as the Privacy Policy describes.
Several commands, one file
Paste as many commands as you like, one after another or separated by a semicolon or &&. Each becomes its own service. The service name comes from --name, or from the image name when there is none, so ghcr.io/org/app:1.2 becomes app. Two containers from the same image get a numbered suffix.
The tool connects the services when it can. If one command uses --network container:vpn and another has --name vpn, the first gets network_mode: service:vpn and a depends_on entry. --volumes-from and --link are resolved the same way. Lines such as docker network create or docker volume create are not needed in Compose, so they are noted and skipped.
Which options are converted
The tool reads more than 70 options, in long form, short form, with an equals sign, or combined as in -itd.
- Ports and storage: -p, --expose, -v, --mount (bind, volume and tmpfs, including read-only), --tmpfs, --volumes-from, --env-file.
- Identity and process: --name, --hostname, --domainname, --user, -w, --entrypoint, the command, --init, --privileged, --read-only, -i and -t.
- Networking: --network (custom, host, none, bridge and container:), --network-alias, --ip, --ip6, --link, --add-host, --dns, --dns-search and --dns-option.
- Security and devices: --cap-add, --cap-drop, --device, --device-cgroup-rule, --security-opt, --group-add, --sysctl and --ulimit.
- Health and logs: --health-cmd and its interval, timeout, retries and start period, --no-healthcheck, --log-driver and --log-opt.
- Resources: --memory, --memory-reservation, --memory-swap, --cpus, --cpu-shares, --cpuset-cpus, --pids-limit, --shm-size, --blkio-weight and --gpus.
- Lifecycle: --restart, --stop-signal, --stop-timeout and --pull.
Ports are always quoted in the file, because an unquoted pair such as 22:22 can be read as a number by some YAML parsers.
Limits, GPUs and health checks
Compose has two places for CPU and memory limits. The service keys mem_limit, cpus and pids_limit are the short form. The deploy.resources block is the form that swarm and recent Compose versions describe. The CPU and memory limits option writes whichever you choose. With it set to deploy.resources, this command gives the file below.
docker run -d --name api --memory 512m --cpus 1.5 --gpus all myorg/api:1.4
services:
api:
image: myorg/api:1.4
container_name: api
deploy:
resources:
limits:
memory: 512m
cpus: "1.5"
reservations:
devices:
- driver: nvidia
capabilities:
- gpu
count: all--gpus always goes to deploy.resources.reservations.devices, with a count or a list of device ids. A health check written as --health-cmd becomes a test list that starts with CMD-SHELL, and the interval, timeout and retries follow as separate keys.
Named volumes and networks
A named volume such as pgdata:/var/lib/postgresql/data is declared in a top-level volumes block, and a custom network in a top-level networks block. By default Compose creates them, with the project name in front of the name. That is right for a fresh start, but it means a volume that docker run already filled is not reused.
To keep that data, set Named volumes and networks to Use existing. The blocks then say external: true, and Compose uses the volume or network that already exists under that exact name.
networks:
backend:
external: true
volumes:
data:
external: trueSecrets, variables and quoting
Passwords typed into a command end up in a file you may commit. The tool warns when a variable name looks like a password, token or key and a plain value is given. Move such values to an env_file or a .env file instead.
A variable without a value, as in -e HOME, is written without a value so Compose reads it from your shell. Compose also fills in $NAME and ${NAME} itself, which docker run left to the shell. A dollar sign inside single quotes in your command is therefore written as $$, so that it stays a literal dollar sign.
docker run -e 'PRICE=$5' -e HOME alpine echo '$HOME'
services:
alpine:
image: alpine
command:
- echo
- $$HOME
environment:
PRICE: $$5
HOME:What is not converted
Some options have no key in Compose. --rm and -d are not needed. -P, --label-file, --cidfile, --volume-driver and a few block IO settings have no matching key or need a hand edit, and a flag the tool does not know is reported too. The panel lists each one with the line it came from and the reason, so nothing is dropped without a trace.
Check the file before you rely on it, and run docker compose config to let Compose validate it. For the other direction, from a compose file to commands, use Compose to Docker Run. To inspect or reformat the YAML, YAML to JSON, JSON to YAML and Sort YAML Keys help.