Docker Run to Compose Command Reference: Syntax, Flags &

docker run to compose is the process of translating a docker run command and its flags into equivalent services, image, ports, volumes, environment, and command declarations in a docker-compose.yml file for declarative multi-container orchestration.

docker run --rm -it progrium/stress --cpu 2 --io 1 --vm 2 --vm-bytes 128M --timeout 10s

The equivalent docker-compose.yml for this command:

version: "3.6"
services:
  stress:
    image: progrium/stress
    command: "--cpu 2 --io 1 --vm 2 --vm-bytes 128M --timeout 10s"

Key rule: --rm and -it are not expressed in Compose because the container lifecycle is managed by docker-compose up / down. Resource limits map to deploy.resources in swarm mode or cpus/mem_limit in version 3.x.

Conversion Mapping Reference

Each docker run flag maps to a YAML key under a service definition. The table below covers the most common mappings validated against Docker Compose v2 and Docker Engine 25.0.3.

Advanced Implementation

Mapping Interactive and Detached Flags

The -it flag combines --interactive and --tty. In Compose:

services:
  debug:
    image: alpine
    stdin_open: true
    tty: true
    command: ["sh"]

-d (detached) is the default when running docker-compose up -d; no explicit YAML key.

Multiple Containers and Dependencies

Convert multiple docker run calls into a single Compose file with depends_on:

docker run -d --name web -p 5000:5000 -v .:/code myapp
docker run -d --name redis redis:alpine

Becomes:

version: "3.6"
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/code
    depends_on:
      - redis
  redis:
    image: redis:alpine

Environment File Handling

Replace multiple -e flags with env_file:

environment:
  - VAR1=value1
  - VAR2=value2
# or
env_file: .env

Networks and Aliases

Define top-level networks for custom bridges:

networks:
  frontend:
    driver: bridge
services:
  app:
    networks:
      frontend:
        aliases:
          - api

Error Resolution & Troubleshooting

Production-Grade Implementation

Use Explicit Version Pinning

Specify version: "3.6" at the top for consistent behavior across Docker Engine versions. Omit version only when using Compose v2 exclusively.

Leverage .env Files for Secrets

Store sensitive data in a .env file referenced by env_file. Never embed secrets in the YAML:

# .env
DB_PASSWORD=s3cret

services:
  db:
    image: postgres:16
    env_file: .env

Implement Healthchecks

Replace --health-cmd with native Compose healthcheck:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 30s
  timeout: 10s
  retries: 3

Minimize Permissions via Read-Only Filesystems

Add read_only: true and mount /tmp as tmpfs:

services:
  app:
    image: myapp
    read_only: true
    tmpfs:
      - /tmp

Automate Conversion with composerize

The open-source tool composerize (composerize.com) accepts a docker run string and outputs a starting docker-compose.yml. It is not perfect for complex commands but accelerates prototyping.

Version Control the Compose File

Keep docker-compose.yml in the same repository as the application code. Use environment-specific override files (docker-compose.override.yml) for local development and exclude them from production branches.

Frequently Asked Questions

# docker run
docker run -v /host/path:/container/path:ro image
# docker-compose.yml
services:
  app:
    image: image
    volumes:
      - type: bind
        source: /host/path
        target: /container/path
        read_only: true

docker compose up --build --force-recreate

docker rm -f mycontainer
docker compose up --force-recreate

docker compose version
docker compose run --platform linux/amd64 service

# Example via composerize (not a CLI tool, web service)
# Paste command at composerize.com