docker-run

Docker Run — Container Lifecycle Management

Complete guidance for running, monitoring, and managing Docker containers.

When to Use

ALWAYS use this skill when the user mentions:

"docker run", "run container", "start container"
"docker ps", "docker stop", "docker restart"
"container resource limits", "memory limit", "CPU limit"
"health check", "healthcheck"
"docker logs", "view logs"
"docker exec", "enter container"
"restart policy", "container restart policy"

Container Lifecycle

docker pull → docker create → docker start → docker run (create+start)
                                                │
                          ┌─────────────────────┼─────────────────────┐
                          ▼                     ▼                     ▼
                      Running              Paused/Stopped         Killed
                          │                     │
                          ▼                     ▼
                      docker stop          docker start
                      docker kill          docker restart
                      docker rm            docker rm -f

`docker run` — Complete Reference

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

# Most common form
docker run -d --name myapp \
  -p 8080:8080 \
  -v /host/path:/container/path \
  -e ENV_VAR=value \
  --restart unless-stopped \
  myimage:tag

Flag	Purpose	Example
`-d`	Detached (background)	`-d`
`--name`	Container name	`--name my-nginx`
`-p`	Port mapping (host:container)	`-p 8080:80`
`-v`	Volume/bind mount	`-v data:/var/lib/mysql`
`-e`	Environment variable	`-e DB_HOST=localhost`
`--env-file`	Load env from file	`--env-file .env`
`--restart`	Restart policy	`--restart unless-stopped`
`--rm`	Auto-remove on stop	`--rm` (for temp containers)

Resource Constraints

# Memory: limit + reservation
docker run --memory=512m --memory-reservation=256m myapp

# CPU: shares (relative) + cpus (absolute)
docker run --cpus=2 --cpu-shares=1024 myapp

# Combined: production-grade limits
docker run -d \
  --memory=1g --memory-swap=1g \
  --cpus=2 \
  --pids-limit=100 \
  myapp

Resource	Flag	Best Practice
Memory	`--memory=512m`	Always set; container can exhaust host memory otherwise
Memory+Swap	`--memory-swap=1g`	Set equal to memory to disable swap
CPU	`--cpus=2`	Hard limit; `--cpu-shares` for relative priority
PIDs	`--pids-limit=100`	Prevent fork bombs
Ulimits	`--ulimit nofile=65536`	File descriptor limits

Health Checks

Dockerfile HEALTHCHECK

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Health Check States

starting → healthy (passes)
         → unhealthy (fails 3 consecutive checks)

# Check health status
docker inspect --format='{{.State.Health.Status}}' myapp

# Health check in compose
# services.app.healthcheck.test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

Restart Policies

Policy	Behavior	Use Case
`no`	Never restart (default)	One-off tasks
`on-failure[:N]`	Restart on non-zero exit, max N times	Batch jobs
`always`	Always restart	Critical services (be careful — infinite loop risk)
`unless-stopped`	Restart unless explicitly stopped	Recommended for most services

docker run --restart unless-stopped myapp
docker update --restart always myapp  # Change policy on running container

Logging & Debugging

# View logs
docker logs myapp                # All logs
docker logs -f myapp             # Follow (tail -f)
docker logs --tail 50 myapp      # Last 50 lines
docker logs --since 10m myapp    # Last 10 minutes

# Execute commands in container
docker exec -it myapp sh         # Interactive shell
docker exec myapp cat /etc/hosts # Run single command

# Inspect state
docker inspect myapp             # Full JSON metadata
docker stats myapp               # Live resource usage
docker top myapp                 # Running processes
docker port myapp                # Port mappings

Signal Handling

docker stop myapp    → SIGTERM → wait 10s → SIGKILL
docker kill myapp    → SIGKILL immediately
docker kill -s HUP myapp → Send custom signal

Signal	docker command	Container effect
SIGTERM	`docker stop`	Graceful shutdown (default)
SIGKILL	`docker kill`	Force kill (no cleanup)
SIGHUP	`docker kill -s HUP`	Reload config (app-specific)

Workflow — Recommended operational workflow

Step 1: Pull or build the image: docker pull or docker build Have the image ready Step 2: Run the container: docker run -d --name myapp -p 8080:8080 -v data:/data --memory 512m myapp Step 3: Verify startup: docker ps + docker logs myapp Confirm it is running normally Step 4: Configure health checks: Ensure HEALTHCHECK is defined in the Dockerfile or specified at runtime Step 5: Monitor operation: docker stats + docker logs -f Monitor continuously

Gotchas — Common Pitfalls

Default --memory=0 (unlimited): Container can consume all host memory. → Recovery: docker run --memory=512m --cpus=1 app; check usage with docker stats.
docker stop timeout: Default 10s grace period. → Recovery: docker stop -t 30 myapp; ensure app handles SIGTERM properly.
docker run creates new container: Running docker run nginx twice creates two containers. → Recovery: docker start <existing-name> to restart; docker ps -a to find stopped containers.
Logs filling disk: JSON-file driver has no rotation by default. → Recovery: docker run --log-opt max-size=10m --log-opt max-file=3 app; existing containers: edit /etc/docker/daemon.json + restart dockerd.
docker exec exit codes: Returns the command's exit code. → Recovery: Use for scripting: docker exec myapp healthcheck.sh || exit 1.

Boundary — Capability boundaries (applicable and non-applicable scenarios)

Category	Scenario	Description
✅ Can do	docker run to run containers	All parameters, resource limits, restart policies
✅ Can do	Health check configuration	HEALTHCHECK instruction + runtime override
✅ Can do	Log management	Log driver selection + rotation configuration
✅ Can do	Enter container for debugging	docker exec / docker attach
⚠️ Requires conditions	--privileged privileged mode	For debugging only, prohibited in production
⚠️ Requires conditions	Modify limits of a running container	Requires `docker update`, some parameters cannot be changed dynamically
❌ Out of scope	Writing a Dockerfile	Use `docker-dockerfile`
❌ Out of scope	Multi-container orchestration	Use `docker-compose`
❌ Out of scope	Image building	Use `docker-build`

When NOT to Use This Skill

❌ Skip	✅ Use Instead
Docker basics / first-time setup	`docker-basics`
Writing Dockerfile	`docker-build`
Multi-container apps	`docker-compose`
Network configuration	`docker-networking`
Storage/Volume management	`docker-storage`

Security & Stability

Always set --memory and --cpus limits in production to prevent noisy-neighbor issues.
Avoid --privileged flag. Use specific --cap-add instead.
Never run containers as root. Use --user flag or USER in Dockerfile.
Use --read-only for stateless containers where possible.
No executable scripts bundled. Guidance only.

📚 Official documentation reference

Documentation	Address
Docker Engine	https://docs.docker.com/engine/
docker run reference	https://docs.docker.com/reference/cli/docker/container/run/
Container management CLI	https://docs.docker.com/reference/cli/docker/container/
Runtime options	https://docs.docker.com/engine/reference/run/
Resource limits	https://docs.docker.com/config/containers/resource_constraints/
Log drivers	https://docs.docker.com/config/containers/logging/

🧭 Docker Skills Journey

📍 You are here: docker-run — Step 3: Container management and operations

← Previous: docker-build — Dockerfile & image building → Next: docker-networking / docker-storage / docker-compose