From docker run to Compose: What Each Flag Really Means

The image name tells Docker what filesystem and default command to start from. It does not explain how the container should connect to the host, where data should persist, which environment variables are required, or what happens after a restart. Compose makes these decisions visible. A good service block should be readable enough that another person can tell what the container needs and what it exposes.

A docker run flag such as -p 8080:80 maps host port 8080 to container port 80. Reversing that meaning is a common mistake. Compose expresses the same relationship under ports. Before copying a mapping, ask which port users or reverse proxies connect to and which port the application listens on inside the container. Avoid exposing ports publicly unless the service actually needs direct access.

Containers are disposable by design. Volumes and bind mounts decide which data survives recreation. A bind mount points at a host path; a named volume is managed by Docker. When translating from run to Compose, preserve the difference. Mounting the wrong host directory can hide files inside the image or write data somewhere unexpected. For databases and uploaded files, volume review is more important than syntax.

The -e flag is convenient, but copied commands often include passwords, tokens, or connection strings. Compose can move configuration into environment sections or env files, but that does not automatically make secrets safe. Do not commit real secrets to the repository. Use the project's existing secret handling, deployment environment, or secret manager. If you publish examples, use clear placeholders instead of realistic credentials.

A one-off docker run command may exit and stay stopped. A service often needs a restart policy. Compose lets you document whether a container should restart unless stopped, always restart, or remain manual. This is an operational decision, not a formatting detail. A crash-looping container with an aggressive restart policy can hide errors or create noise. Pair restart rules with logs and health checks when the service matters.

Some docker run flags translate directly. Others require Compose-specific keys, a different structure, or manual review. Interactive flags, device access, network modes, capabilities, user IDs, DNS settings, and platform constraints can carry security implications. A converter can produce a draft, but advanced flags should be reviewed against Docker and Compose documentation before production use.

Start from a representative command with image, ports, volumes, environment variables, and restart behavior. Convert it into a service. Rename the service and volumes clearly. Remove secrets. Run a configuration validation command. Start locally if safe, inspect logs, and confirm the app writes data where expected. Then commit the Compose file with comments for any non-obvious flag. The goal is maintainable operations, not just a prettier command.