@hivehub/rulebook 5.4.1 → 5.5.0

package/templates/services/DOCKER.md

@@ -1,124 +1,124 @@
-<!-- DOCKER:START -->
-# Docker Instructions
-
-**CRITICAL**: Follow these Docker best practices for all container builds.
-
-## Build Patterns
-
-### Multi-Stage Builds
-Use multi-stage builds to minimize final image size and separate build-time dependencies from runtime:
-
-```dockerfile
-FROM node:20-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-FROM node:20-alpine AS runtime
-RUN adduser -D appuser
-USER appuser
-WORKDIR /app
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-HEALTHCHECK --interval=30s --timeout=3s CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
-CMD ["node", "dist/index.js"]
-```
-
-### Base Image Selection
-- Pin base image versions: `node:20-alpine` not `node:latest`
-- Prefer `-alpine` or `-slim` variants for smaller images
-- Use official images from Docker Hub verified publishers
-
-## Security Requirements
-
-### Non-Root User
-ALL containers MUST run as a non-root user:
-```dockerfile
-RUN adduser -D appuser
-USER appuser
-```
-
-### Secrets
-- NEVER copy secrets (`.env`, credentials, keys) into image layers
-- Use Docker secrets or runtime environment variables instead
-- Scan images with `docker scout cves` or `trivy image` before pushing
-- Add `--no-cache` to package install commands to reduce attack surface
-
-### Image Scanning
-```bash
-# Docker Scout (built-in)
-docker scout cves <image>
-
-# Trivy
-trivy image <image>
-```
-
-## Required Instructions
-
-### HEALTHCHECK
-ALL production images MUST include a HEALTHCHECK:
-```dockerfile
-HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
-  CMD curl -f http://localhost:3000/health || exit 1
-```
-
-### .dockerignore Requirements
-Every Docker project MUST have a `.dockerignore` file containing at minimum:
-```
-.git
-node_modules
-dist
-coverage
-*.log
-.env*
-.DS_Store
-*.md
-.vscode
-.idea
-```
-
-## Common Patterns
-
-### Layer Caching
-Order Dockerfile instructions from least-changing to most-changing:
-```dockerfile
-# 1. Base image (rarely changes)
-FROM node:20-alpine
-
-# 2. System dependencies (changes rarely)
-RUN apk add --no-cache curl
-
-# 3. Package files (changes when deps change)
-COPY package*.json ./
-RUN npm ci --only=production
-
-# 4. Application code (changes frequently)
-COPY . .
-```
-
-### Production Optimization
-```dockerfile
-# Use npm ci for deterministic installs
-RUN npm ci --only=production
-
-# Remove unnecessary files
-RUN rm -rf /tmp/* /var/cache/apk/*
-
-# Set NODE_ENV
-ENV NODE_ENV=production
-```
-
-## Best Practices
-
-- Use `.dockerignore` to exclude unnecessary files from build context
-- One process per container (do not run multiple services in one container)
-- Use `COPY` over `ADD` unless extracting archives
-- Combine RUN commands to reduce layers: `RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*`
-- Set explicit `WORKDIR` instead of `RUN cd`
-- Use `EXPOSE` to document listening ports
-- Tag images with semantic versions, not just `latest`
-
-<!-- DOCKER:END -->
+<!-- DOCKER:START -->
+# Docker Instructions
+
+**CRITICAL**: Follow these Docker best practices for all container builds.
+
+## Build Patterns
+
+### Multi-Stage Builds
+Use multi-stage builds to minimize final image size and separate build-time dependencies from runtime:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+RUN adduser -D appuser
+USER appuser
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+HEALTHCHECK --interval=30s --timeout=3s CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
+CMD ["node", "dist/index.js"]
+```
+
+### Base Image Selection
+- Pin base image versions: `node:20-alpine` not `node:latest`
+- Prefer `-alpine` or `-slim` variants for smaller images
+- Use official images from Docker Hub verified publishers
+
+## Security Requirements
+
+### Non-Root User
+ALL containers MUST run as a non-root user:
+```dockerfile
+RUN adduser -D appuser
+USER appuser
+```
+
+### Secrets
+- NEVER copy secrets (`.env`, credentials, keys) into image layers
+- Use Docker secrets or runtime environment variables instead
+- Scan images with `docker scout cves` or `trivy image` before pushing
+- Add `--no-cache` to package install commands to reduce attack surface
+
+### Image Scanning
+```bash
+# Docker Scout (built-in)
+docker scout cves <image>
+
+# Trivy
+trivy image <image>
+```
+
+## Required Instructions
+
+### HEALTHCHECK
+ALL production images MUST include a HEALTHCHECK:
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+```
+
+### .dockerignore Requirements
+Every Docker project MUST have a `.dockerignore` file containing at minimum:
+```
+.git
+node_modules
+dist
+coverage
+*.log
+.env*
+.DS_Store
+*.md
+.vscode
+.idea
+```
+
+## Common Patterns
+
+### Layer Caching
+Order Dockerfile instructions from least-changing to most-changing:
+```dockerfile
+# 1. Base image (rarely changes)
+FROM node:20-alpine
+
+# 2. System dependencies (changes rarely)
+RUN apk add --no-cache curl
+
+# 3. Package files (changes when deps change)
+COPY package*.json ./
+RUN npm ci --only=production
+
+# 4. Application code (changes frequently)
+COPY . .
+```
+
+### Production Optimization
+```dockerfile
+# Use npm ci for deterministic installs
+RUN npm ci --only=production
+
+# Remove unnecessary files
+RUN rm -rf /tmp/* /var/cache/apk/*
+
+# Set NODE_ENV
+ENV NODE_ENV=production
+```
+
+## Best Practices
+
+- Use `.dockerignore` to exclude unnecessary files from build context
+- One process per container (do not run multiple services in one container)
+- Use `COPY` over `ADD` unless extracting archives
+- Combine RUN commands to reduce layers: `RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*`
+- Set explicit `WORKDIR` instead of `RUN cd`
+- Use `EXPOSE` to document listening ports
+- Tag images with semantic versions, not just `latest`
+
+<!-- DOCKER:END -->

package/templates/services/DOCKER_COMPOSE.md

@@ -1,168 +1,168 @@
-<!-- DOCKER_COMPOSE:START -->
-# Docker Compose Instructions
-
-**CRITICAL**: Follow these Docker Compose best practices for local development and multi-container orchestration.
-
-## Version and Structure
-
-### File Organization
-- Use `docker-compose.yml` for base configuration
-- Use `docker-compose.override.yml` for local development overrides
-- Use `docker-compose.prod.yml` for production-specific settings
-- Do NOT commit secrets in `docker-compose.yml` — use `.env` files
-
-### Compose File
-```yaml
-services:
-  app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: runtime
-    env_file: [.env]
-    ports:
-      - "3000:3000"
-    depends_on:
-      db:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 3s
-      retries: 3
-      start_period: 10s
-    deploy:
-      resources:
-        limits:
-          memory: 512M
-          cpus: "0.5"
-    restart: unless-stopped
-```
-
-## Required Fields Per Service
-
-### Health Checks
-ALL services MUST define a healthcheck:
-```yaml
-healthcheck:
-  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-  interval: 30s
-  timeout: 3s
-  retries: 3
-```
-
-### Resource Limits
-ALL services SHOULD define resource limits for production-like environments:
-```yaml
-deploy:
-  resources:
-    limits:
-      memory: 512M
-      cpus: "0.5"
-    reservations:
-      memory: 128M
-      cpus: "0.25"
-```
-
-### Restart Policy
-```yaml
-restart: unless-stopped
-```
-
-### Named Volumes
-Use named volumes (not bind mounts) for persistent data:
-```yaml
-volumes:
-  postgres_data:
-  redis_data:
-
-services:
-  db:
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-```
-
-## Environment Variables
-
-### Configuration
-- Use `.env` file: `env_file: [.env]`
-- Never hardcode credentials in docker-compose.yml
-- Document all required environment variables in README or `.env.example`
-
-### .env.example Pattern
-```bash
-# Database
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=myapp
-DB_USER=myuser
-DB_PASSWORD=changeme
-
-# Redis
-REDIS_URL=redis://localhost:6379
-
-# Application
-NODE_ENV=development
-PORT=3000
-```
-
-## Networking
-
-### Service Communication
-- Services on the same network communicate by service name
-- Use explicit networks for isolation:
-```yaml
-networks:
-  frontend:
-  backend:
-
-services:
-  app:
-    networks: [frontend, backend]
-  db:
-    networks: [backend]
-```
-
-## Common Patterns
-
-### Development Setup
-```yaml
-services:
-  app:
-    build: .
-    volumes:
-      - .:/app
-      - /app/node_modules
-    environment:
-      - NODE_ENV=development
-    command: npm run dev
-```
-
-### Database with Init Scripts
-```yaml
-services:
-  db:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: myapp
-      POSTGRES_USER: myuser
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U myuser"]
-      interval: 10s
-      retries: 5
-```
-
-## Best Practices
-
-- Use `depends_on` with `condition: service_healthy` for startup ordering
-- Pin image versions (e.g., `postgres:16-alpine`, not `postgres:latest`)
-- Keep compose files DRY with YAML anchors or extension fields (`x-common`)
-- Use `docker compose up --build` to rebuild images after code changes
-- Run `docker compose down -v` to clean up volumes during development
-- Separate concerns: one service per container
-
-<!-- DOCKER_COMPOSE:END -->
+<!-- DOCKER_COMPOSE:START -->
+# Docker Compose Instructions
+
+**CRITICAL**: Follow these Docker Compose best practices for local development and multi-container orchestration.
+
+## Version and Structure
+
+### File Organization
+- Use `docker-compose.yml` for base configuration
+- Use `docker-compose.override.yml` for local development overrides
+- Use `docker-compose.prod.yml` for production-specific settings
+- Do NOT commit secrets in `docker-compose.yml` — use `.env` files
+
+### Compose File
+```yaml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: runtime
+    env_file: [.env]
+    ports:
+      - "3000:3000"
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 10s
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "0.5"
+    restart: unless-stopped
+```
+
+## Required Fields Per Service
+
+### Health Checks
+ALL services MUST define a healthcheck:
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+  interval: 30s
+  timeout: 3s
+  retries: 3
+```
+
+### Resource Limits
+ALL services SHOULD define resource limits for production-like environments:
+```yaml
+deploy:
+  resources:
+    limits:
+      memory: 512M
+      cpus: "0.5"
+    reservations:
+      memory: 128M
+      cpus: "0.25"
+```
+
+### Restart Policy
+```yaml
+restart: unless-stopped
+```
+
+### Named Volumes
+Use named volumes (not bind mounts) for persistent data:
+```yaml
+volumes:
+  postgres_data:
+  redis_data:
+
+services:
+  db:
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+```
+
+## Environment Variables
+
+### Configuration
+- Use `.env` file: `env_file: [.env]`
+- Never hardcode credentials in docker-compose.yml
+- Document all required environment variables in README or `.env.example`
+
+### .env.example Pattern
+```bash
+# Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+DB_USER=myuser
+DB_PASSWORD=changeme
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Application
+NODE_ENV=development
+PORT=3000
+```
+
+## Networking
+
+### Service Communication
+- Services on the same network communicate by service name
+- Use explicit networks for isolation:
+```yaml
+networks:
+  frontend:
+  backend:
+
+services:
+  app:
+    networks: [frontend, backend]
+  db:
+    networks: [backend]
+```
+
+## Common Patterns
+
+### Development Setup
+```yaml
+services:
+  app:
+    build: .
+    volumes:
+      - .:/app
+      - /app/node_modules
+    environment:
+      - NODE_ENV=development
+    command: npm run dev
+```
+
+### Database with Init Scripts
+```yaml
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: myuser
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U myuser"]
+      interval: 10s
+      retries: 5
+```
+
+## Best Practices
+
+- Use `depends_on` with `condition: service_healthy` for startup ordering
+- Pin image versions (e.g., `postgres:16-alpine`, not `postgres:latest`)
+- Keep compose files DRY with YAML anchors or extension fields (`x-common`)
+- Use `docker compose up --build` to rebuild images after code changes
+- Run `docker compose down -v` to clean up volumes during development
+- Separate concerns: one service per container
+
+<!-- DOCKER_COMPOSE:END -->