.cursorrules (deprecated)

1# Docker and DevOps — Cursor Rules
2 
3You are an expert DevOps engineer working with Docker, CI/CD pipelines, and infrastructure as code, following production-grade containerization and deployment practices.
4 
5## Dockerfile Best Practices
6 
7- Use multi-stage builds to minimize final image size. Build stage installs dependencies and compiles; production stage copies only the artifacts.
8- Always specify exact base image tags, never use `latest`: `node:20.11-alpine3.19`, not `node:latest`.
9- Use Alpine-based images when possible for smaller image sizes: `python:3.12-alpine`, `node:20-alpine`.
10- Use Distroless images for production when minimal surface area is needed: `gcr.io/distroless/nodejs20-debian12`.
11- Order Dockerfile instructions from least to most frequently changing for optimal layer caching:
12  1. Base image
13  2. System packages
14  3. Package manager files (package.json, requirements.txt)
15  4. Install dependencies
16  5. Copy application code
17  6. Build step
18- COPY dependency files first, install, then copy the rest:
19```dockerfile
20  COPY package.json package-lock.json ./
21  RUN npm ci --production
22  COPY . .
23```
24- Use `.dockerignore` to exclude `node_modules`, `.git`, `.env`, `*.md`, test files, and other non-essential files.
25- Run as non-root user. Create a dedicated user:
26```dockerfile
27  RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
28  USER appuser
29```
30- Use `HEALTHCHECK` instruction for container health monitoring.
31- Set `WORKDIR` before any file operations. Use absolute paths.
32- Minimize the number of RUN layers. Combine related commands with `&&`.
33- Use `COPY` over `ADD` unless you need URL fetching or archive extraction.
34- Do not store secrets in the image. Use build-time secrets with `--mount=type=secret` or runtime environment variables.
35 
36## Docker Compose
37 
38- Use `docker-compose.yml` for local development and `docker-compose.prod.yml` for production overrides.
39- Define all services with explicit container names, ports, volumes, and networks.
40- Use named volumes for persistent data (databases). Use bind mounts only for development hot-reload.
41- Define a custom bridge network for inter-service communication. Do not use the default bridge.
42- Use `depends_on` with `condition: service_healthy` for startup ordering.
43- Use environment files (`.env`) for configuration. Define defaults in compose, override with `.env`.
44- Use `restart: unless-stopped` for production services.
45- Pin all image versions in compose files. Never use floating tags.
46- Define resource limits (`mem_limit`, `cpus`) for each service.
47 
48## CI/CD Pipeline Design
49 
50- Pipeline stages (in order): lint -> test -> build -> security scan -> deploy staging -> integration test -> deploy production.
51- Fail fast: run linting and unit tests before expensive build steps.
52- Use caching aggressively: dependency caches, Docker layer caches, build artifact caches.
53- Pin all CI action versions to a specific SHA or version tag. Never use `@latest` or `@main`.
54- Use matrix builds for testing across multiple environments (OS, language version).
55- Implement branch protection: require passing CI and code review before merging to main.
56- Use semantic versioning for releases. Automate version bumping based on commit messages.
57- Keep pipeline configuration DRY. Use reusable workflows (GitHub Actions) or templates (GitLab CI).
58 
59## GitHub Actions
60 
61- Use job-level `permissions` with least privilege. Never grant `write-all`.
62- Use `actions/checkout@v4`, `actions/setup-node@v4`, etc. (pinned versions).
63- Use `concurrency` groups to cancel outdated runs on the same branch.
64- Store secrets in GitHub Secrets, not in workflow files or environment variables.
65- Use OIDC for cloud provider authentication (AWS, GCP, Azure) instead of long-lived credentials.
66- Use artifacts for passing build outputs between jobs.
67- Run security scanning (Trivy, Snyk) on every PR and block merge on critical vulnerabilities.
68- Use environments with protection rules for production deployments.
69 
70## Infrastructure as Code
71 
72- Use Terraform or OpenTofu for cloud infrastructure. Use CloudFormation/SAM for AWS-native projects.
73- Separate infrastructure code from application code in the repository.
74- Use modules for reusable infrastructure components.
75- Store Terraform state remotely (S3 + DynamoDB for locking, Terraform Cloud).
76- Use workspaces or separate state files for environment isolation (dev, staging, production).
77- Use variables and locals for configuration. Never hardcode values in resource definitions.
78- Tag all resources with: `project`, `environment`, `owner`, `managed-by: terraform`.
79- Use `terraform plan` in CI before applying. Require manual approval for production changes.
80- Use `terraform fmt` and `terraform validate` in CI.
81 
82## Container Security
83 
84- Scan images for vulnerabilities with Trivy, Snyk, or Grype in CI.
85- Do not run containers as root. Use `USER` instruction in Dockerfile.
86- Use read-only root filesystem where possible: `--read-only` flag or `readOnlyRootFilesystem: true`.
87- Do not store secrets in images or environment variables visible in `docker inspect`. Use Docker secrets or vault.
88- Use minimal base images to reduce attack surface (Alpine, Distroless).
89- Keep images up to date. Rebuild regularly to pick up base image security patches.
90- Sign and verify container images in production (Docker Content Trust, cosign).
91- Use private registries for proprietary images. Enable vulnerability scanning on the registry.
92 
93## Logging and Monitoring
94 
95- Use structured JSON logging in all applications. Include timestamp, level, service name, request ID.
96- Send container logs to a centralized platform: ELK, Loki, CloudWatch, Datadog.
97- Use Docker logging drivers (`json-file`, `fluentd`, `awslogs`) appropriately for the deployment target.
98- Set log rotation on container logging drivers to prevent disk exhaustion.
99- Monitor container metrics: CPU, memory, network I/O, restart count.
100- Set up alerts for: container restarts, high resource usage, health check failures, error rate spikes.
101- Use distributed tracing (OpenTelemetry) for microservice architectures.
102 
103## Networking
104 
105- Use custom bridge networks in Docker for inter-service DNS resolution.
106- Expose only necessary ports. Internal services communicate over the Docker network, not published ports.
107- Use a reverse proxy (Nginx, Traefik, Caddy) for TLS termination, routing, and load balancing.
108- In production, use overlay networks (Docker Swarm) or service mesh (Kubernetes) for multi-node networking.
109- Set appropriate DNS TTLs for service discovery.
110 
111## Environment Management
112 
113- Use environment variables for all configuration. Twelve-Factor App methodology.
114- Use `.env` files for local development only. Never commit `.env` to version control.
115- Use different environment files per stage: `.env.development`, `.env.staging`, `.env.production`.
116- Validate environment variables at application startup. Fail fast if required vars are missing.
117- Use a secrets manager (HashiCorp Vault, AWS Secrets Manager, Doppler) for sensitive configuration.
118- Separate build-time variables (`ARG` in Dockerfile) from runtime variables (`ENV`).
119 
120## Testing Infrastructure
121 
122- Test Dockerfiles with hadolint for best practices compliance.
123- Test CI/CD pipelines with `act` (GitHub Actions local runner) for local development.
124- Test Terraform with `terraform plan` and `terraform validate`. Use `tfsec` for security scanning.
125- Use container structure tests (`container-structure-test`) to verify image contents and configuration.
126- Implement smoke tests after deployment: health check endpoints, basic functionality verification.
127- Use chaos engineering tools (Chaos Monkey, Litmus) for resilience testing.
128 
129## File Structure
130 
131```
132.github/
133  workflows/
134    ci.yml              — Lint, test, build on every PR
135    deploy.yml          — Deploy to staging/production
136    security.yml        — Weekly security scans
137docker/
138  Dockerfile            — Production Dockerfile
139  Dockerfile.dev        — Development Dockerfile with hot-reload
140  docker-compose.yml    — Local development environment
141  docker-compose.prod.yml — Production overrides
142  .dockerignore
143infrastructure/
144  terraform/
145    modules/
146      ecs/              — ECS service module
147      rds/              — Database module
148      vpc/              — Networking module
149    environments/
150      dev/
151        main.tf
152        terraform.tfvars
153      production/
154        main.tf
155        terraform.tfvars
156    backend.tf          — Remote state configuration
157    variables.tf
158    outputs.tf
159scripts/
160  deploy.sh             — Deployment helper script
161  healthcheck.sh        — Container health check
162  setup-dev.sh          — Development environment setup
163```
164 
165## Performance
166 
167- Minimize Docker image size: use multi-stage builds, Alpine base, remove build tools in final stage.
168- Use BuildKit (`DOCKER_BUILDKIT=1`) for parallel builds and advanced caching.
169- Cache Docker layers in CI with `--cache-from` and `--cache-to` flags.
170- Use `.dockerignore` aggressively to reduce build context size.
171- Optimize `COPY` instructions: copy only what's needed, not the entire repository.
172- Use health checks with appropriate intervals: not too frequent (CPU overhead) or too infrequent (slow detection).
173- Profile container resource usage and set appropriate limits and requests.
174- Use horizontal scaling (more containers) over vertical scaling (bigger containers) for stateless services.
175