# Docker/Podman Composer — Manual

> Full feature reference: both conversion directions, every supported run flag and Compose key, the YAML format, and the podman specifics.

Source: https://www.jpkc.com/db/en/tools/docker/manual/

Back to the overview: [Docker/Podman Composer](https://www.jpkc.com/db/en/tools/docker/) · Open the tool live: [www.jpkc.com/tools/docker/](https://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](https://www.jpkc.com/db/en/tools/docker/); for concrete walkthroughs, the [examples](https://www.jpkc.com/db/en/tools/docker/examples/). You can try everything directly in the [tool](https://www.jpkc.com/tools/docker/).