.cursorrules (deprecated)

1# Docker & Containerization — Cursor Rules
2# Comprehensive rules for Docker, Docker Compose, and container best practices
3 
4## Project Context
5You are working on a project that uses Docker for containerization. Containers are used
6for local development, CI/CD pipelines, and production deployment. The codebase includes
7Dockerfiles for application services and docker-compose files for orchestrating
8multi-container environments.
9 
10## Tech Stack
11- Docker Engine 24+
12- Docker Compose v2
13- Multi-stage builds
14- Container registries (Docker Hub, GitHub Container Registry, ECR)
15- Orchestration: Docker Compose (dev), Kubernetes or ECS (production)
16 
17## Dockerfile Best Practices
18 
19### Multi-Stage Build Pattern
20```dockerfile
21# Stage 1: Build
22FROM node:20-alpine AS builder
23WORKDIR /app
24 
25# Install dependencies first (better cache utilization)
26COPY package.json package-lock.json ./
27RUN npm ci --production=false
28 
29# Copy source and build
30COPY . .
31RUN npm run build
32 
33# Stage 2: Production
34FROM node:20-alpine AS production
35WORKDIR /app
36 
37# Create non-root user
38RUN addgroup -S appgroup && adduser -S appuser -G appgroup
39 
40# Copy only production dependencies and built artifacts
41COPY --from=builder /app/package.json /app/package-lock.json ./
42RUN npm ci --production && npm cache clean --force
43 
44COPY --from=builder /app/dist ./dist
45 
46# Switch to non-root user
47USER appuser
48 
49EXPOSE 3000
50HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
51  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
52 
53CMD ["node", "dist/server.js"]
54```
55 
56### Python Multi-Stage
57```dockerfile
58FROM python:3.12-slim AS builder
59WORKDIR /app
60 
61RUN pip install --no-cache-dir uv
62COPY pyproject.toml uv.lock ./
63RUN uv sync --frozen --no-dev --no-editable
64 
65COPY . .
66 
67FROM python:3.12-slim AS production
68WORKDIR /app
69 
70RUN useradd --create-home --no-log-init appuser
71COPY --from=builder /app/.venv .venv
72COPY --from=builder /app/src ./src
73 
74USER appuser
75ENV PATH="/app/.venv/bin:$PATH"
76 
77EXPOSE 8000
78HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
79  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
80 
81CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
82```
83 
84## Dockerfile Rules
85 
86### Layer Ordering (Most to Least Frequently Changed)
871. Base image
882. System dependencies
893. Create user
904. Copy dependency manifests (package.json, requirements.txt)
915. Install dependencies
926. Copy source code
937. Build step
948. Runtime configuration (ENV, EXPOSE, HEALTHCHECK, CMD)
95 
96### Image Size Optimization
97- Use `-alpine` or `-slim` base images
98- Use multi-stage builds to exclude build tools from production
99- Combine `RUN` commands to reduce layers: `RUN apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/*`
100- Use `.dockerignore` to exclude unnecessary files
101- Remove caches after installing packages: `npm cache clean --force`, `pip --no-cache-dir`
102- Don't install dev dependencies in production: `npm ci --production`
103 
104### .dockerignore
105```
106node_modules
107.git
108.env
109.env.*
110*.md
111.vscode
112.idea
113coverage
114.nyc_output
115dist
116__pycache__
117*.pyc
118.pytest_cache
119.mypy_cache
120docker-compose*.yml
121Dockerfile*
122```
123 
124### Security
125- Never run as root — create and switch to a non-root user
126- Don't store secrets in the image (use environment variables or secrets manager)
127- Pin base image versions: `node:20.11-alpine` not `node:latest`
128- Scan images for vulnerabilities: `docker scout cves`
129- Use `COPY` instead of `ADD` (ADD has extra behaviors: URL fetch, tar extraction)
130- Don't install unnecessary packages (no `vim`, `curl` in production unless needed for healthcheck)
131- Set read-only filesystem where possible: `--read-only`
132 
133## Docker Compose
134 
135### Development Setup
136```yaml
137# docker-compose.yml
138services:
139  app:
140    build:
141      context: .
142      dockerfile: Dockerfile
143      target: builder          # Use build stage for development
144    ports:
145      - "3000:3000"
146    volumes:
147      - .:/app                 # Mount source for hot reload
148      - /app/node_modules      # Prevent overwriting container's node_modules
149    environment:
150      - NODE_ENV=development
151      - DATABASE_URL=postgres://postgres:postgres@db:5432/appdb
152    depends_on:
153      db:
154        condition: service_healthy
155    command: npm run dev
156
157  db:
158    image: postgres:16-alpine
159    ports:
160      - "5432:5432"
161    environment:
162      POSTGRES_USER: postgres
163      POSTGRES_PASSWORD: postgres
164      POSTGRES_DB: appdb
165    volumes:
166      - pgdata:/var/lib/postgresql/data
167    healthcheck:
168      test: ["CMD-SHELL", "pg_isready -U postgres"]
169      interval: 5s
170      timeout: 5s
171      retries: 5
172
173  redis:
174    image: redis:7-alpine
175    ports:
176      - "6379:6379"
177    healthcheck:
178      test: ["CMD", "redis-cli", "ping"]
179      interval: 5s
180      timeout: 5s
181      retries: 5
182
183volumes:
184  pgdata:
185```
186 
187### Compose Best Practices
188- Use `depends_on` with `condition: service_healthy` for startup ordering
189- Define healthchecks on all services
190- Use named volumes for persistent data
191- Use `.env` file for environment variables
192- Override with `docker-compose.override.yml` for local customizations
193- Use `profiles` for optional services (like monitoring tools)
194 
195## Container Runtime
196 
197### Environment Variables
198- Use `ENV` in Dockerfile for build-time defaults
199- Use `environment` in docker-compose for runtime configuration
200- Use Docker secrets or external secret managers for sensitive values
201- Never hardcode secrets in Dockerfiles or compose files
202 
203### Networking
204- Use Docker Compose service names as hostnames (`db`, `redis`)
205- Only expose ports that need external access
206- Use internal networks for service-to-service communication
207- Define custom networks for service isolation
208 
209### Health Checks
210- Every service must have a health check
211- Health checks should be lightweight and fast
212- Test the actual service (HTTP endpoint, database ping), not just process existence
213- Set reasonable intervals (10-30s) and retries (3-5)
214 
215## Development Workflow
216```bash
217# Build and start all services
218docker compose up --build
219 
220# Run in background
221docker compose up -d
222 
223# View logs
224docker compose logs -f app
225 
226# Execute command in running container
227docker compose exec app npm run test
228 
229# Rebuild a single service
230docker compose up --build app
231 
232# Clean up everything
233docker compose down -v --rmi local
234```
235 
236## Production Considerations
237- Use specific image tags, never `latest`
238- Set resource limits (memory, CPU)
239- Use restart policies: `restart: unless-stopped`
240- Log to stdout/stderr (Docker captures and forwards)
241- Use read-only root filesystem with tmpfs for writable needs
242- Implement graceful shutdown (handle SIGTERM)
243- Use init process: `--init` flag or `tini`
244 
245## Common Pitfalls
246- Using `latest` tag in production (unpredictable builds)
247- Running as root (security risk)
248- Not using `.dockerignore` (large image, slow builds, secrets leaked)
249- Installing dev dependencies in production images
250- Not using multi-stage builds (bloated production images)
251- Copying `node_modules` from host into container (platform mismatch)
252- Not setting healthchecks (orchestrator can't detect unhealthy containers)
253- Hardcoding configuration instead of using environment variables
254- Not handling SIGTERM (container takes 10s to stop instead of shutting down gracefully)
255- Storing state in the container filesystem (data lost on restart)
256