docker

Docker Cursor Rules

You are an expert Docker developer. Follow these rules:

Dockerfiles

• Use specific base image tags (node:20-alpine, not node:latest) — latest changes without warning and breaks builds
• Order layers from least to most frequently changing: OS deps → language deps → build tools → application code. Each change invalidates all layers after it
• Multi-stage builds to reduce final image size: build stage with dev dependencies, production stage copies only the compiled output. A Node.js app can go from 1GB to 150MB
• Copy dependency files first, install, then copy source: COPY package*.json ./ → RUN npm ci → COPY . . — this caches the expensive install step when only source code changes
• .dockerignore is not optional: exclude node_modules, .git, *.md, .env, test files — without it, your build context is huge and cache invalidation is unpredictable
• RUN npm ci not RUN npm install — ci uses the lockfile exactly, install might update it

Security

• Never run as root: RUN addgroup -S app && adduser -S app -G app then USER app before CMD. Root in a container = root on the host if there's an escape
• Secrets never in the image: no ENV SECRET=..., no COPY .env . — use runtime env vars, Docker secrets, or mounted config files
• Scan images with Trivy or Snyk in CI — vulnerabilities in base images are your vulnerabilities
• Minimal base images: alpine (5MB), distroless (no shell at all), or slim variants. Full Debian/Ubuntu images carry hundreds of unnecessary packages
• HEALTHCHECK instruction so Docker knows when your container is actually ready, not just running. Without it, a crashed app inside a "running" container gets no restart

Compose

• Named volumes for persistent data (db-data:) — anonymous volumes get garbage collected and your data disappears
• Resource limits on every service: deploy.resources.limits.memory: 512M — one runaway container shouldn't OOM the entire host
• depends_on with condition: service_healthy (not just service_started) to wait for actual readiness — database containers start fast but take seconds to accept connections
• .env files for configuration, but never commit them — use .env.example with placeholder values
• restart: unless-stopped for production services — always restarts even when you manually stop, which is annoying during debugging