docker run Command Builder

docker run in depth: flags, networking, volumes, and resource limits

The docker run command is the workhorse of every container workflow — it creates a new container from an image and starts it in a single call. Behind the scenes it composes docker create + docker start, applies dozens of namespace, cgroup, and seccomp options, attaches volumes, wires networks, and forwards ports. The general shape is docker run [OPTIONS] IMAGE [COMMAND] [ARG...], and even though most production containers are launched by Compose, Kubernetes, or Nomad, the underlying primitive every orchestrator wraps is still this same call.

Lifecycle and process flags

• -d — detach: run in the background and print the container ID.
• -i — interactive: keep STDIN open even when not attached.
• -t — allocate a TTY (pseudo-terminal).
• -it — the canonical combo for an interactive shell: docker run -it alpine sh.
• --rm — automatically remove the container when it exits (great for one-shot tools).
• --name web — assign a stable name instead of the random adjective_noun default.
• --restart unless-stopped — policies: no (default), always, unless-stopped, on-failure[:N].

Ports, volumes, env vars, and networks

Networking and persistence are where the real wiring happens:

-p 8080:80           publish container :80 on host :8080
-p 127.0.0.1:8080:80 bind only to localhost (do not expose publicly)
-P                   publish all EXPOSE'd ports on random host ports
-v /host:/container  bind mount a host path
-v data:/var/lib/db  named volume (portable, managed by Docker)
--mount type=bind,...  modern, more explicit syntax
-e KEY=value         set an env var
--env-file .env      load a whole file of KEY=value lines
--network host       share the host network namespace (Linux only)
--network app-net    join a user-defined bridge (DNS between containers)

Named volumes are almost always preferable to bind mounts: they survive container removal, are managed by Docker, and are easy to back up. Bind mounts make sense for local development where you want live code reloads.

Resource limits and security

• --memory 512m --memory-swap 512m — hard RAM cap, no swap.
• --cpus 1.5 — fractional CPU shares (1.5 cores worth of time).
• --pids-limit 200 — defend against fork bombs.
• -u 1000:1000 — run as a non-root UID/GID inside the container.
• -w /app — set the working directory.
• --read-only — make the root filesystem read-only (pair with --tmpfs /tmp).
• --cap-drop ALL --cap-add NET_BIND_SERVICE — drop every Linux capability and add back only what you need.
• --security-opt no-new-privileges — block setuid privilege escalation.
• --gpus all — expose NVIDIA GPUs (requires nvidia-container-toolkit).
• --privileged — gives the container nearly full host access; avoid unless you are running Docker-in-Docker or a system service that truly needs it.

Worked examples and related commands

# Quick interactive shell, auto-cleanup
docker run --rm -it alpine sh

# Nginx exposed on host port 8080, named, auto-restart
docker run -d --name web --restart unless-stopped \
  -p 8080:80 nginx:1.27-alpine

# Postgres with named volume, resource limits, secrets in env-file
docker run -d --name pg \
  -v pgdata:/var/lib/postgresql/data \
  --env-file ./pg.env \
  --memory 1g --cpus 1 \
  -p 5432:5432 postgres:16

# Enter a running container
docker exec -it web sh

# Follow logs, stop, remove
docker logs -f web
docker stop web && docker rm web

Best practices and alternatives

Pin image tags — :latest is a convention, not a contract, and a silent upgrade can break a production service overnight. Always set --memory and --cpus: an unbounded container can starve every neighbour on the host. Avoid --privileged; if you genuinely need a capability, add it explicitly with --cap-add. Add a HEALTHCHECK in the Dockerfile (or --health-cmd at runtime) so orchestrators can detect zombie processes.

For multi-container apps use docker compose up instead of stitching docker run calls — Compose v2 is now a built-in Docker plugin. Podman is a drop-in compatible alternative that runs rootless by default; nerdctl is the containerd-native CLI; for production orchestration you eventually graduate to Kubernetes or Nomad.

FAQ

What is the difference between docker stop and docker kill? stop sends SIGTERM, waits ten seconds (configurable with -t), then SIGKILL. kill goes straight to SIGKILL. Always prefer stop so the process can flush and exit cleanly.

Will the container die when the main process exits? Yes — the container lives as long as PID 1 lives. If PID 1 backgrounds itself, the container exits immediately. Use a foreground entrypoint or a init shim like tini (built in via --init).

Named volume or bind mount? Named volumes for state you want Docker to manage and back up (databases, app data). Bind mounts for source code during development and config files you edit on the host.

How do I get GPU acceleration? Install nvidia-container-toolkit on the host, then add --gpus all (or --gpus '"device=0,1"' for specific cards). Verify with docker run --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi.

Do I need to rebuild the image after a code change? Yes for production images — docker build -t app:v2 . then docker run app:v2. For development, bind-mount the source with -v $(pwd):/app so the running container picks up edits live.