Docker/Podman Composer — Manual

Back to the overview: Docker/Podman Composer · Open the tool live: www.jpkc.com/tools/docker/

This manual describes the Docker/Podman Composer in full: what happens in each of the two conversion directions, which run flags and Compose keys are actually supported, what the YAML format looks like, and where the limits are. The tool's interface is in English, so tab and button names are given in their original spelling.

Structure: three tabs, one client-side engine

The tool has three tabs: Run → Compose, Compose → Run, and Reference. The first two are the converters; the third is a built-in lookup sheet. Both converters run entirely in the browser — the tokenizer, flag parser, YAML serializer, and the js-yaml parser are all JavaScript. There is no server fetch and no API; your input never leaves the browser. Both editors are built on the ACE editor with syntax highlighting for shell (sh) and YAML.

Direction 1: Run → Compose

In the Run → Compose tab you paste a docker run or podman run command into the Docker / Podman Run Command field and click Convert to YAML. The result appears below in the Docker Compose YAML field. The Example button loads a sample command; Clear empties both fields.

How the command is read

Before the flags are evaluated, a tokenizer splits the command line. It handles:

• Line continuations with a backslash (\ at end of line) — long, multi-line commands are correctly joined into one command.
• Double quotes ("…") with the usual escapes (\n, \t) and single quotes ('…') as literal text. So something like --health-cmd "curl -fs http://localhost/" stays a single argument.

After that, a leading docker/podman prefix and the run subcommand are skipped, then the flags are parsed. Both spellings --flag value and --flag=value are supported. Combined short flags such as -it or -dp are split into their individual flags (only the boolean parts take effect). The first non-flag argument is treated as the image; everything after it becomes the command. Unknown flags are silently skipped.

The service name in the YAML comes from --name if set (lowercased, invalid characters become _); without --name it is derived from the image name (last path segment without tag, e.g. nginx:1.27-alpine → nginx).

Supported value flags (flag → Compose key)

These flags expect a value and map to a Compose key. Flags given multiple times (ports, volumes, env …) end up as a YAML list.

• Identity: --name → container_name; --hostname/-h → hostname; --platform → platform
• Ports & expose: -p/--publish → ports; --expose → expose
• Volumes: -v/--volume → volumes; --tmpfs → tmpfs
• Environment: -e/--env → environment; --env-file → env_file
• Network: --network/--net → networks; --dns → dns; --dns-search → dns_search; --dns-opt/--dns-option → dns_opt; --add-host → extra_hosts
• Lifecycle & signals: --restart → restart; --stop-signal → stop_signal; --stop-timeout → stop_grace_period
• Runtime: -u/--user → user; -w/--workdir → working_dir; --entrypoint → entrypoint
• Labels: -l/--label → labels
• Resources: -m/--memory → mem_limit; --memory-swap → memswap_limit; --memory-reservation → mem_reservation; -c/--cpu-shares → cpu_shares; --cpus → cpus; --cpuset-cpus → cpuset; --shm-size → shm_size; --ulimit → ulimits (e.g. nofile=1024:2048)
• Devices & security: --device → devices; --cap-add → cap_add; --cap-drop → cap_drop; --security-opt → security_opt
• IPC/PID & kernel: --ipc → ipc; --pid → pid; --sysctl → sysctls; --group-add → group_add
• Logging: --log-driver → logging.driver; --log-opt → logging.options (parsed as key=value)
• Health check: --health-cmd → healthcheck.test (as [CMD-SHELL, …]); --health-interval, --health-timeout, --health-retries, --health-start-period → the matching healthcheck.* fields
• Links (deprecated): --link → links

One special case: --network-alias is recognized but discarded (there's no direct Compose equivalent at the service level).

Supported boolean flags (no value)

• -t/--tty → tty: true
• -i/--interactive → stdin_open: true
• --privileged → privileged: true
• --read-only → read_only: true
• --init → init: true
• --no-healthcheck → healthcheck.disable: true
• -d/--detach → discarded (implicit in Compose)
• --rm → discarded (has no Compose equivalent)

The YAML output format

The output starts with a services: block, under it the service with image: first, followed by the remaining keys in a fixed, logical order (identity, runtime flags, ports/volumes, environment, network, labels, devices/security, resources), and finally command, logging, healthcheck, ulimits. No version: line is generated (modern Compose spec, where the field is obsolete). Values are quoted only when YAML requires it (e.g. a pure number meant as a string, such as "3").

The result field carries an "editable" badge and is genuinely editable: you can add right inside the tool the things a converter can't derive from a run command — depends_on, a build: block, or top-level network and volume definitions. Copy copies the YAML; docker-compose.yml downloads it as a file (a locally generated blob).

Direction 2: Compose → Run

In the Compose → Run tab you paste a docker-compose.yml into the Docker Compose YAML field and click Convert to Commands. Below, the Generated Run Commands field shows a separate run command for each service, each preceded by a # <service-name> comment line. This output field is read-only; Copy copies its contents.

Choosing docker or podman

In the footer of the input field there's a Runtime radio switch with docker (default) and podman. It only determines which command word the generated lines start with — docker run … or podman run …. The flags themselves are identical, because Podman reproduces the docker run options in a largely compatible way.

What is read and generated

The YAML parser (js-yaml) accepts both a complete Compose file (with a services: key) and a bare services map. Each generated command starts with <runtime> run -d and --name (from container_name, otherwise the service name). After that, the Compose keys are translated back into run flags — essentially the reverse of the table above:

• restart, hostname, platform, user (→ --user), working_dir (→ --workdir)
• ports (short string or long object with host_ip/published/target/protocol), expose
• volumes (string or object with source/target/read_only → :ro), tmpfs
• environment (list or object → KEY=VALUE), env_file
• networks (list or object → one --network each), dns, dns_search, dns_opt (→ --dns-option), extra_hosts (→ --add-host)
• labels, cap_add, cap_drop, security_opt, devices
• privileged, read_only, tty (→ -t), stdin_open (→ -i), init, entrypoint
• ipc, pid, shm_size, sysctls, group_add, links
• Resources: mem_limit (→ --memory), memswap_limit (→ --memory-swap), mem_reservation, cpu_shares, cpus, cpuset (→ --cpuset-cpus)
• logging (→ --log-driver + --log-opt key=value), healthcheck (→ --health-cmd/--health-interval/… or --no-healthcheck for disable: true), ulimits
• stop_signal, stop_grace_period (→ --stop-timeout)
• image (required; if missing, an IMAGE_MISSING placeholder is inserted) and finally command

Arguments with special characters are automatically quoted shell-safely. Short commands stay on one line; longer ones are wrapped onto several neatly indented lines with backslash continuations, keeping --flag value pairs together on one line.

What is NOT translated on Compose import

These Compose constructs have no docker run equivalent and are ignored when generating the commands (the built-in Reference tab lists them as "Compose-only Features"):

• depends_on — start order and health conditions between services
• build — build an image from a Dockerfile
• profiles — conditional service activation
• deploy — Swarm/replica/resource constraints
• secrets / configs — Swarm secrets and configs
• Top-level volumes/networks definitions (with driver options) — only a service's reference to a network becomes --network; the actual driver definition is dropped

The Reference tab

The third tab is a built-in lookup sheet and needs no input:

• Flag Reference: docker run → Compose — a table grouped by topic (Container Identity, Image & Command, Ports & Volumes, Environment, Network, Lifecycle, Runtime Flags, Security, Resources, Logging, Healthcheck, Labels) with the run flag, Compose key, and a note.
• Compose-only Features — the constructs above with no run equivalent.
• Restart Policies — no (default, never restart), always, unless-stopped, on-failure, and on-failure:3 (max 3 retries).
• Tips — short notes on line continuations, combined flags, and the editable YAML.

Limits — in brief

• Single-container run only. One run command produces exactly one service; run options without a Compose equivalent (e.g. --rm, --detach, --network-alias) and unknown flags are discarded.
• Compose-only constructs are lost when you convert from Compose to run (depends_on, build, profiles, deploy, secrets/configs, top-level networks/volumes).
• No docker/podman in the background. The tool doesn't run or check anything against a real engine — it's a pure text-to-text translator.

For the introduction and target audiences, see the overview page; for concrete walkthroughs, the examples. You can try everything directly in the tool.