Mastering Docker: Precision in Container Creation from the CLI

Deployed an application in Docker and puzzled why the environment behaves differently in CI vs. your laptop? The real cause often comes down to how the container is started. A single flag alters everything—network, volume, isolation, or lifecycle.

Core Command: docker run — Start, Stop, Repeat

The backbone of container execution is the docker run command. It encapsulates image selection, resource allocation, environment injection, and IO handling—all in a single invocation.

Canonical Syntax:

docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]

• OPTIONS: Influence container runtime characteristics (-d, --name, etc).
• IMAGE: Source for the filesystem and startup process.
• COMMAND, ARG...: Optional overrides; replaces entrypoint/cmd.

Typical Usage Patterns

1. Service in the Background (Web Server Example)

docker run -d --name nginx-prod -p 8080:80 nginx:1.25-alpine

Purpose: Exposes port 80 of nginx:1.25-alpine to port 8080 on the host. Container is daemonized (-d), named for clarity (--name).
Practical note: Omitting --name yields random names. This complicates automation/scripts that require precise IDs.

2. Interactive Session for Debugging

docker run --rm -it ubuntu:22.04 bash

• Drops you into an Ubuntu shell. Container auto-removes on exit (--rm).
• Useful for testing commands, troubleshooting base images.

3. Data Persistence: Bind Mount

docker run -d -v /srv/sql:/var/lib/mysql --name sql-data mysql:8.1

• Attaches host directory /srv/sql to container’s /var/lib/mysql.
• Ensures database state survives container teardown.
• Gotcha: SELinux/AppArmor can block volume access if contexts aren’t set.

Real-World Failure Mode: Port Conflict

Attempting to run multiple containers mapping the same host port:

docker run -d -p 5432:5432 --name pg1 postgres:16
docker run -d -p 5432:5432 --name pg2 postgres:16

Yields:

docker: Error response from daemon: driver failed programming external connectivity on endpoint pg2: Bind for 0.0.0.0:5432 failed: port is already allocated.

Lesson: Host ports must be unique per container.

Persistent Storage: Volumes vs. Bind Mounts

• Use named volumes for loosely-coupled, Docker-managed data:

  docker run -v pgdata:/var/lib/postgresql/data postgres:16
  

  Volume is referenced by name; Docker manages its path.

• Use bind mounts for direct host<->container file sharing.
  Downside: increased dependency on host filesystem structure.

Known issue: On macOS/Windows, bind mount IO can be slow due to VM abstraction.

Injecting Secrets or Config at Runtime

Suppose you need to pass credentials or configuration options:

docker run -e MYSQL_ROOT_PASSWORD='s3cr3t' mysql:8.1

Note: Hardcoding secrets in CLI can leak via shell history. For production, consider Docker secrets with Swarm or orchestrators.

Advanced: Resource Constraints

To prevent containers from starving the host:

docker run --cpus=1.5 --memory=512m busybox:1.36 top

• Caps at 1.5 CPU cores and 512MB RAM.
• Useful for multi-tenant hosts or CI resource allocation.

Container Cleanup and Troubleshooting

Short-lived jobs clutter docker ps -a with exited containers unless --rm is set.

• Best practice: Use --rm for ad hoc operations.
• To manually purge stopped containers:

  docker container prune
  

Side Effect: Orphaned volumes are not deleted unless specified with volume prune—volumes can quickly consume disk space.

Brief Recap

• Use docker run as the entry point for nearly all container lifecycles.
• Key options matter: name, detach, volume, env-vars, resource limits.
• Always check for port conflicts on shared hosts.
• Bind mounts provide convenience but can introduce portability/speed pitfalls.
• Rely on named volumes for robust storage in production.

Try this minimal check to confirm Docker works as expected:

docker run hello-world

For real workloads, iterate on the docker run flags above. Sometimes the simplest configuration reveals the most about your application's behavior across environments. Trade-offs between flexibility, reproducibility, and security are ever-present—rarely does one set of flags fit all deployments.