Smart Setup Docker Containers

Create production-optimized Docker configurations with multi-stage builds, development workflows, Docker Compose orchestration, and security hardening for your detected application stack.

When to Use This Command

Run this command when...

• You need a Dockerfile with multi-stage builds, layer optimization, and security best practices for your application
• You want a Docker Compose setup that orchestrates your application with databases, caches, and message queues
• You need separate development and production Docker configurations with hot reloading for dev
• You want container security hardening including non-root users, minimal base images, and vulnerability scanning
• You need CI/CD integration for building, tagging, and pushing images to a container registry

Quick Start

Copy
# .claude/commands/smart-setup-docker-containers.yaml
name: Smart Setup Docker Containers
description: Setup optimized Docker containerization with Compose
inputs:
  - name: environment
    description: "dev, production, or both"
    default: "both"

Copy
# Setup for both development and production
claude "smart-setup-docker-containers"

# Setup development environment only
claude "smart-setup-docker-containers --environment dev"

# Setup with specific services
claude "smart-setup-docker-containers --services postgres,redis"

Output:
  [detect] Application: Node.js 20 + TypeScript
  [create] Dockerfile (multi-stage: deps, build, runtime)
  [create] Dockerfile.dev (with hot reload)
  [create] docker-compose.yml (app + postgres + redis)
  [create] docker-compose.dev.yml (dev overrides)
  [create] .dockerignore
  [optimize] Final image: 145MB (from 1.2GB base)
  [security] Non-root user, no secrets in layers
  Done. 5 files created. Run: docker compose up

Core Concepts

Concept	Description
Multi-Stage Builds	Separate build and runtime stages to minimize final image size by excluding build tools and source
Development Workflow	Dev containers with volume mounts for hot reloading, debugger attachment, and live code changes
Service Orchestration	Docker Compose configuration with application, database, cache, and supporting services
Security Hardening	Non-root USER directive, minimal base images (alpine/distroless), and no secrets baked into layers
Layer Optimization	Strategic COPY ordering and dependency caching to maximize Docker layer cache hits

Docker Architecture:
  ┌──────────────────────────────────────┐
  │         docker-compose.yml           │
  ├──────────┬───────────┬───────────────┤
  │   App    │ Database  │    Cache      │
  │ ┌──────┐ │ ┌───────┐ │ ┌───────────┐ │
  │ │Node  │ │ │Postgres│ │ │   Redis   │ │
  │ │Multi │ │ │  :5432 │ │ │   :6379   │ │
  │ │Stage │ │ └───────┘ │ └───────────┘ │
  │ └──────┘ │           │               │
  │  :3000   │  Volume   │    Volume     │
  └──────────┴───────────┴───────────────┘

Configuration

Parameter	Type	Default	Description
environment	string	"both"	Target: dev, production, or both
services	string	auto-detected	Additional services: postgres, redis, mongodb, rabbitmq (comma-separated)
base_image	string	"alpine"	Base image type: alpine (small), debian (compatible), or distroless (minimal)
registry	string	""	Container registry URL for image tagging (e.g., ghcr.io/org)
port	integer	auto-detected	Application port to expose

Best Practices

1. Use multi-stage builds always -- Even simple applications benefit from separating build and runtime stages. A Node.js app drops from 1+ GB to under 200MB with proper staging.
2. Order COPY commands strategically -- Copy package.json and lock files before source code. This lets Docker cache the dependency installation layer when only source code changes.
3. Never run as root -- Add a USER node or USER appuser directive in your Dockerfile. Running as root inside containers is a security risk that most vulnerability scanners flag.
4. Use .dockerignore aggressively -- Exclude node_modules, .git, test files, and documentation from the build context. This speeds up builds and reduces image size.
5. Pin base image versions -- Use node:20.11-alpine instead of node:latest. Unpinned tags can introduce breaking changes or vulnerabilities when the base image updates.

Common Issues

1. Hot reload not working in dev -- Volume mounts must map your source directory into the container. Ensure docker-compose.dev.yml has the correct volume path and the file watcher is configured for container environments.
2. Image too large -- Common causes: using non-alpine base images, including dev dependencies in the final stage, or copying unnecessary files. Review each COPY statement and the .dockerignore file.
3. Port conflicts with local services -- Docker services may conflict with locally running databases or applications on the same ports. Change the host port mapping in docker-compose.yml (e.g., 5433:5432).