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", "运行容器", "启动容器"
• "docker ps", "docker stop", "docker restart"
• "容器资源限制", "memory limit", "CPU limit"
• "健康检查", "healthcheck"
• "docker logs", "查看日志"
• "docker exec", "进入容器"
• "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 — 推荐操作流程

Step 1: 拉取或构建镜像: docker pull 或 docker build 准备好镜像 Step 2: 运行容器: docker run -d --name myapp -p 8080:8080 -v data:/data --memory 512m myapp Step 3: 验证启动: docker ps + docker logs myapp 确认运行正常 Step 4: 配置健康检查: 确保 HEALTHCHECK 在 Dockerfile 中定义或运行时指定 Step 5: 监控运行: docker stats + docker logs -f 持续观察

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 — 能力边界（适用与不适用场景）

分类	场景	说明
✅ 能做	docker run 运行容器	所有参数、资源限制、重启策略
✅ 能做	健康检查配置	HEALTHCHECK 指令 + 运行时覆盖
✅ 能做	日志管理	日志驱动选择 + 轮转配置
✅ 能做	进入容器调试	docker exec / docker attach
⚠️ 需条件	--privileged 特权模式	仅调试用，生产禁止
⚠️ 需条件	修改运行中容器限制	需 docker update，部分参数不可动态改
❌ 超范围	编写 Dockerfile	使用 docker-dockerfile
❌ 超范围	多容器编排	使用 docker-compose
❌ 超范围	镜像构建	使用 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.

📚 官方文档参考

文档	地址
Docker 引擎	https://docs.docker.com/engine/
docker run 参考	https://docs.docker.com/reference/cli/docker/container/run/
容器管理 CLI	https://docs.docker.com/reference/cli/docker/container/
运行时选项	https://docs.docker.com/engine/reference/run/
资源限制	https://docs.docker.com/config/containers/resource_constraints/
日志驱动	https://docs.docker.com/config/containers/logging/

🧭 Docker Skills Journey

📍 You are here: docker-run — Step 3: 容器管理与运维

← Previous: docker-build — Dockerfile & 镜像构建 → Next: docker-networking / docker-storage / docker-compose