Mastering docker run: Container Flags, Port Mapping, Volumes, and Env Vars

The docker run command is the foundational entry point for creating and launching container instances from Docker images. Mastering its CLI flags allows developers to control network port exposure, persistent volume storage, environment variables, resource limits, and process lifecycles.

In this practical guide, we break down every essential option inside docker run.

Anatomy of the Production docker run Command

Consider this production-ready container execution command:

docker run -d \
  --name api-server \
  --restart unless-stopped \
  -p 8080:8000 \
  -v app_data:/app/data \
  --env-file .env \
  --memory="512m" \
  --cpus="1.5" \
  my-api-image:v1.2.0

[docker run] -> Action
  [-d] -> Detached background process
  [--name api-server] -> Assign explicit container identifier
  [--restart unless-stopped] -> Auto-restart daemon policy
  [-p 8080:8000] -> Port forwarding (Host Port 8080 : Container Port 8000)
  [-v app_data:/app/data] -> Volume mount for persistent storage
  [--env-file .env] -> Environment variable injection
  [--memory="512m"] -> Memory resource cap
  [my-api-image:v1.2.0] -> Image name and version tag

Detailed Option Breakdown

1. Execution Mode: -d vs -it

• -d (Detached): Runs container in the background and prints the container ID. Used for web servers and background workers.
• -it (Interactive Terminal): Connects your terminal STDIN/STDOUT to the container process. Used for interactive shell sessions (docker run -it alpine sh).

2. Port Forwarding: -p host_port:container_port

Maps a host network port to a container port:

• -p 8080:80: Exposes container port 80 on host localhost:8080.
• -p 127.0.0.1:5432:5432: Restricts host access exclusively to localhost interface for security.

3. Persistent Volumes: -v and --mount

Containers have an ephemeral file system that resets when deleted. Use volumes to persist data:

• Named Volume: -v db_data:/var/lib/postgresql/data (Managed by Docker daemon).
• Bind Mount: -v $(pwd)/src:/app/src (Maps host directory directly into container; ideal for local development code reload).

4. Environment Variables: -e and --env-file

Inject runtime configuration into container processes:

• Single variable: -e NODE_ENV=production
• Env file: --env-file .env.production

5. Auto-Cleanup and Restart Policies

• --rm: Automatically deletes the container when it exits (ideal for build tasks or database migrations).
• --restart unless-stopped: Re-launches the container if it crashes or if the Docker daemon reboots.

Useful Everyday Command Patterns

# Launch a quick throwaway Redis CLI session
docker run --rm -it redis:alpine redis-cli -h 172.17.0.1

# Run PostgreSQL database with persistent storage and custom password
docker run -d \
  --name local-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16-alpine

Conclusion

Understanding docker run flags empowers you to run, inspect, and configure containerized applications with precision.

References & Further Reading

• Official Docker CLI Reference: docker run
• Docker Storage & Volumes Documentation