Docker & DevOps Workspace

The docker run command executes a single container from the command line, accepting flags for image name, port mappings, volume mounts, environment variables, and networking options. It is quick for one-off testing but becomes unwieldy once a setup needs more than a couple of interdependent flags to remember and retype correctly.

Docker Compose uses a YAML file, conventionally docker-compose.yml, to define one or more services declaratively: each service specifies its image, ports, volumes, environment, and dependencies on other services, all version-controlled and shareable as a single file rather than a shell history of run commands.

Translating CLI flags to Compose YAML follows a consistent mapping: -p 80:80 becomes a ports: list entry, -v /data:/var/data becomes a volumes: list entry, and -e KEY=VAL becomes an entry under environment:. Multiple instances of the same flag become multiple list items or map entries under the corresponding YAML key.

Compose additionally introduces depends_on to express startup ordering between services, and a shared networks: definition so services can reach each other by service name rather than by IP address — neither has a direct docker run equivalent, since a single run command has no concept of other containers.

A common task is converting an existing set of docker run commands, often collected from documentation or a teammate's notes, into a single reproducible Compose file. Use the Docker Run to Docker Compose Converter to translate each command's flags into the corresponding YAML structure automatically, rather than hand-mapping each flag.

Once converted, review the generated startup-ordering assumptions if your services need to start in a specific order, a database before the application that connects to it, for example — the converter can translate explicit flags, but implicit ordering assumptions in the original run commands need to be added by hand using depends_on.

Check port mappings against what your application actually needs exposed externally versus what only needs to be reachable by other containers on the same Compose network — over-publishing ports on a host is a common security oversight when migrating from ad hoc run commands.

For any volume mount that held important data under the original run command, confirm the converted volumes entry preserves both the host path and the container path exactly — a subtle path mismatch here is one of the most common causes of data appearing to disappear after switching to Compose.

Mistake: forgetting that named volumes and bind mounts behave differently. A bind mount, a host filesystem path, reflects live edits from the host immediately; a named volume is managed by Docker itself and is not directly editable from the host filesystem the same way. Using the wrong one for a given use case is a common source of confusion about why file changes are not showing up where expected.

Mistake: assuming services in the same Compose file can reach each other by localhost. Each service runs in its own network namespace; services reach each other by service name over the shared Compose network, not by localhost or 127.0.0.1, which only refers to the container itself.

Troubleshooting: if a converted Compose service fails to start with a port-already-in-use error that did not occur with the original run command, check for a leftover container from a previous run occupying the same host port — Compose does not automatically clean up containers left behind by manually run docker run commands.

Troubleshooting: if an environment variable that worked with -e in docker run is not showing up inside the container after converting to Compose, check for YAML indentation errors under the environment key first — a misindented entry is silently dropped or misattached to the wrong service rather than raising a clear error.

The Compose file format itself is defined by the Compose Specification, a project maintained collaboratively by Docker and other container-ecosystem vendors rather than an IETF or ISO standard, after the earlier v1/v2/v3 version distinctions were consolidated into a single schema.

Docker images and the container runtime format more broadly are defined by the OCI (Open Container Initiative) Image Format and Runtime Specifications, which is why images built by Docker can run under other OCI-compliant runtimes.

YAML, the format Compose files are written in, follows the YAML specification covered in more depth in the YAML hub — Compose's specific schema is layered on top of general YAML syntax, not a separate format.

For a single container during local development or a quick test, docker run is faster to iterate with. For anything with more than one service, or anything you need to reproduce reliably later or share with a team, use Compose — the YAML file itself becomes the documentation of how the system is configured. See the Docker Run vs Compose comparison for the detailed tradeoff.

For production-scale orchestration, multiple hosts, automatic failover, rolling deployments, Compose alone is not designed for that; Kubernetes is the standard choice at that scale, at the cost of significantly more operational complexity. See the Docker Compose vs Kubernetes comparison for when that added complexity is actually justified versus when Compose remains sufficient.