Cursor rule

1---
2globs:
3  - "**/Dockerfile"
4  - "**/.dockerignore"
5  - "docker-compose.yml"
6---
7 
8# Docker and Containerization Rules
9 
10## Dockerfile Best Practices
11 
12### Multi-Stage Builds
13```dockerfile
14# Build stage
15FROM node:22-alpine AS builder
16WORKDIR /app
17COPY package*.json ./
18RUN npm ci
19COPY . .
20RUN npm run build
21 
22# Production stage
23FROM node:22-alpine AS production
24WORKDIR /app
25COPY --from=builder /app/dist ./dist
26CMD ["node", "dist/main.js"]
27```
28 
29### Layer Optimization
30- Order from least to most frequently changing
31- Copy dependency files before source code
32- Use `.dockerignore` to exclude unnecessary files
33 
34```dockerfile
35# ✅ Good - Dependencies cached separately
36COPY package.json package-lock.json ./
37RUN npm ci
38COPY . .
39 
40# ❌ Bad
41COPY . .
42RUN npm ci
43```
44 
45### Base Images
46- Use official images
47- Prefer Alpine for smaller size
48- Pin specific versions (avoid `latest`)
49 
50```dockerfile
51# ✅ Good
52FROM python:3.11-alpine
53FROM node:22-alpine
54 
55# ❌ Bad
56FROM python:latest
57```
58 
59## Python Dockerfile (hermes-api)
60 
61```dockerfile
62FROM python:3.11-slim as base
63 
64ENV PYTHONUNBUFFERED=1 \
65    PYTHONDONTWRITEBYTECODE=1 \
66    PIP_NO_CACHE_DIR=1
67 
68WORKDIR /app
69 
70# System dependencies (ffmpeg for yt-dlp)
71RUN apt-get update && apt-get install -y ffmpeg && \
72    rm -rf /var/lib/apt/lists/*
73 
74# Python dependencies
75COPY pyproject.toml uv.lock ./
76RUN pip install uv && uv pip install --system -r uv.lock
77 
78COPY . .
79 
80# Non-root user
81RUN useradd -m -u 1000 hermes && \
82    chown -R hermes:hermes /app
83 
84USER hermes
85 
86EXPOSE 8000
87 
88CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
89```
90 
91## Node.js Dockerfile (hermes-app)
92 
93```dockerfile
94FROM node:22-alpine AS builder
95WORKDIR /app
96 
97COPY package.json pnpm-lock.yaml ./
98RUN corepack enable pnpm && pnpm install --frozen-lockfile
99 
100COPY . .
101RUN pnpm build
102 
103# Production
104FROM nginx:alpine AS production
105COPY nginx.conf /etc/nginx/conf.d/default.conf
106COPY --from=builder /app/dist /usr/share/nginx/html
107 
108EXPOSE 80
109CMD ["nginx", "-g", "daemon off;"]
110```
111 
112## .dockerignore
113 
114```dockerignore
115# Version control
116.git
117.gitignore
118 
119# Dependencies
120node_modules
121__pycache__
122*.pyc
123 
124# Environment
125.env
126.env.*
127!.env.example
128 
129# Development
130*.log
131*.md
132!README.md
133.vscode
134 
135# Build artifacts
136dist
137build
138*.egg-info
139 
140# Tests
141tests
142**/__tests__
143*.test.js
144*.test.ts
145 
146# Docker
147Dockerfile
148.dockerignore
149docker-compose*.yml
150```
151 
152## docker-compose.yml
153 
154```yaml
155version: '3.8'
156
157services:
158  api:
159    build:
160      context: ./packages/hermes-api
161      dockerfile: Dockerfile
162    container_name: hermes-api
163    ports:
164      - "8000:8000"
165    environment:
166      - HERMES_SECRET_KEY=${HERMES_SECRET_KEY}
167      - REDIS_URL=redis://redis:6379/0
168    volumes:
169      - ./packages/hermes-api/data:/app/data
170      - ./packages/hermes-api/downloads:/app/downloads
171    depends_on:
172      - redis
173    restart: unless-stopped
174
175  app:
176    build:
177      context: ./packages/hermes-app
178      dockerfile: Dockerfile
179    container_name: hermes-app
180    ports:
181      - "3000:80"
182    environment:
183      - VITE_API_URL=http://localhost:8000
184    depends_on:
185      - api
186    restart: unless-stopped
187
188  redis:
189    image: redis:7-alpine
190    container_name: hermes-redis
191    ports:
192      - "6379:6379"
193    volumes:
194      - redis_data:/data
195    restart: unless-stopped
196
197  celery:
198    build:
199      context: ./packages/hermes-api
200      dockerfile: Dockerfile
201    container_name: hermes-celery
202    command: celery -A app.tasks.celery_app worker --loglevel=info
203    environment:
204      - REDIS_URL=redis://redis:6379/0
205    volumes:
206      - ./packages/hermes-api/downloads:/app/downloads
207    depends_on:
208      - redis
209    restart: unless-stopped
210
211volumes:
212  redis_data:
213```
214 
215 
216### Volume Mounts
217 
218```yaml
219# Development - mount source code
220volumes:
221  - ./packages/hermes-api:/app
222  - /app/node_modules
223 
224# Production - persistent data only
225volumes:
226  - ./data:/app/data
227  - ./downloads:/app/downloads
228```
229 
230### Environment Variables
231```yaml
232environment:
233  - SECRET_KEY=${SECRET_KEY:-changeme}
234  - DEBUG=${DEBUG:-false}
235  - LOG_LEVEL=${LOG_LEVEL:-info}
236```
237 
238## Security
239 
240### Non-Root Users
241```dockerfile
242RUN useradd -m -u 1000 appuser
243RUN chown -R appuser:appuser /app
244USER appuser
245```
246 
247### Secrets
248- Never hardcode secrets
249- Use environment variables
250- Use build-time arguments sparingly
251 
252## Health Checks
253 
254```dockerfile
255HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
256  CMD curl -f http://localhost:8000/api/v1/health || exit 1
257```
258 
259```yaml
260services:
261  api:
262    healthcheck:
263      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
264      interval: 30s
265      timeout: 3s
266      retries: 3
267```
268 
269## Development vs Production
270 
271### Development Override
272```yaml
273# docker-compose.override.yml
274services:
275  api:
276    volumes:
277      - ./packages/hermes-api:/app
278    environment:
279      - DEBUG=true
280    command: uvicorn app.main:app --reload --host 0.0.0.0
281```
282 
283### Production
284```yaml
285# docker-compose.prod.yml
286services:
287  api:
288    build:
289      target: production
290    environment:
291      - DEBUG=false
292    restart: always
293```
294 
295Usage:
296```bash
297# Development
298docker compose up
299 
300# Production
301docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
302```
303