Docker Cursor Rules Template

---
description: "Dockerfile Best Practices"
alwaysApply: false
---
- Use multi-stage builds to minimize image size.
- Use specific base image tags — avoid :latest.
- Use    spaces for indentation.
- Combine RUN commands with && to reduce layers.
- Use .dockerignore to exclude unnecessary files.
- Use COPY over ADD unless you need URL or archive extraction.

---
description: "Docker Compose"
alwaysApply: false
---
- Define services in docker-compose.yml with explicit dependencies.
- Use depends_on with healthcheck conditions for startup ordering.
- Use named volumes for persistent data.
- Use environment variables and .env files — never hardcode secrets.
- Use profiles for optional services.
- Pin service image versions — don't use :latest in compose files.

---
description: "Security"
alwaysApply: false
---
- Never run containers as root — use USER directive.
- Use non-root base images when available (node:slim, python:slim).
- Scan images with docker scout or trivy before deployment.
- Use secrets management (Docker secrets, HashiCorp Vault) — not env vars.
- Use read-only root filesystem when possible (--read-only).
- Limit container capabilities with --cap-drop and --cap-add.

---
description: "Image Optimization"
alwaysApply: false
---
- Use Alpine or slim base images for smaller attack surface.
- Leverage build cache: copy dependency files before source code.
- Use --no-cache-dir for pip, --production for npm.
- Clean up package manager caches in the same RUN layer.
- Use layer caching strategically — order COPY commands by change frequency.
- Set resource limits (--memory, --cpus) for predictable performance.