Running Containers
Master docker run flags — environment variables, port mapping, restart policies, resource limits
Skills taught: docker.run-flags, docker.environment-vars, docker.restart-policy, docker.resource-limits
The full docker run flag toolkit
docker run \
-d \
--name my-api \
-p 3000:3000 \
-e DATABASE_URL="postgres://localhost/mydb" \
-e NODE_ENV=production \
--env-file .env \
-v /data/uploads:/app/uploads \
--restart unless-stopped \
--memory 512m \
--cpus 1.0 \
myapi:1.4
# Flag breakdown:
# -d run in background (detached)
# --name my-api give the container a name
# -p 3000:3000 host:container port mapping
# -e KEY=value set an environment variable
# --env-file .env load all vars from a .env file
# -v /host/path:/c/path mount a host directory as a volume
# --restart unless-stopped restart automatically (except manual stop)
# --memory 512m cap RAM at 512 MB
# --cpus 1.0 limit to 1 CPU core
Environment variables — the right way
# ❌ Never bake secrets into an image:
# ENV DATABASE_PASSWORD=mysecret ← visible in docker history, image layers
# ✅ Pass secrets at runtime:
docker run -e DATABASE_URL="postgres://user:pass@db:5432/myapp" myapi
# ✅ Even better — use an .env file:
# .env file contents:
# DATABASE_URL=postgres://user:pass@db:5432/myapp
# REDIS_URL=redis://redis:6379
# JWT_SECRET=supersecret123
docker run --env-file .env myapi
# ✅ Best for teams — Docker secrets or external secret managers:
# (AWS Secrets Manager, HashiCorp Vault, GitHub Actions secrets)
Restart policies
- no (default) — never restart. Use for one-off containers.
- always — always restart, even after docker daemon restarts. Use for critical services.
- unless-stopped — restart always, except when manually stopped. Best for most production services.
- on-failure[:max-retries] — restart only on non-zero exit code. Good for job containers.
# Production web server — should always be up
docker run -d --restart unless-stopped -p 80:80 nginx
# Database — restart on crash, max 5 times
docker run -d --restart on-failure:5 postgres:16
# One-off data migration script — don't restart
docker run --restart no my-migration-script
# Check restart policy of a running container
docker inspect my-api --format '{{.HostConfig.RestartPolicy.Name}}'
Container lifecycle
# States: created → running → paused | stopped | exited
# Created (not started)
docker create --name my-app -p 3000:3000 myapi
# Start
docker start my-app
# Pause (freeze all processes — RAM preserved)
docker pause my-app
docker unpause my-app
# Stop gracefully (SIGTERM → 10s grace → SIGKILL)
docker stop my-app
docker stop --time 30 my-app # extend grace period to 30s
# Force kill immediately
docker kill my-app
# Remove (must be stopped first)
docker rm my-app
docker rm -f my-app # force: stop + remove in one
Frequently Asked Questions
How do I see the resource usage of all running containers?
docker stats — shows a live, htop-style view of CPU%, MEM USAGE, NET I/O, and BLOCK I/O for all running containers. Add a container name to watch just one: docker stats my-api. Add --no-stream for a one-shot snapshot.