anchi-toolkit 1.0.0 → 1.2.1

package/dist/skills/devops/references/docker-basics.md

@@ -0,0 +1,297 @@
+# Docker Basics
+
+Core concepts and workflows for Docker containerization.
+
+## Core Concepts
+
+**Containers:** Lightweight, isolated processes bundling apps with dependencies. Ephemeral by default.
+
+**Images:** Read-only blueprints for containers. Layered filesystem for reusability.
+
+**Volumes:** Persistent storage surviving container deletion.
+
+**Networks:** Enable container communication.
+
+## Dockerfile Best Practices
+
+### Essential Instructions
+```dockerfile
+FROM node:20-alpine              # Base image (use specific versions)
+WORKDIR /app                     # Working directory
+COPY package*.json ./            # Copy dependency files first
+RUN npm install --production     # Execute build commands
+COPY . .                         # Copy application code
+ENV NODE_ENV=production          # Environment variables
+EXPOSE 3000                      # Document exposed ports
+USER node                        # Run as non-root (security)
+CMD ["node", "server.js"]        # Default command
+```
+
+### Multi-Stage Builds (Production)
+```dockerfile
+# Stage 1: Build
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine AS production
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+Benefits: Smaller images, improved security, no build tools in production.
+
+### .dockerignore
+```
+node_modules
+.git
+.env
+*.log
+.DS_Store
+README.md
+docker-compose.yml
+dist
+coverage
+```
+
+## Building Images
+
+```bash
+# Build with tag
+docker build -t myapp:1.0 .
+
+# Build targeting specific stage
+docker build -t myapp:dev --target build .
+
+# Build for multiple platforms
+docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.0 .
+
+# View layers
+docker image history myapp:1.0
+```
+
+## Running Containers
+
+```bash
+# Basic run
+docker run myapp:1.0
+
+# Background (detached)
+docker run -d --name myapp myapp:1.0
+
+# Port mapping (host:container)
+docker run -p 8080:3000 myapp:1.0
+
+# Environment variables
+docker run -e NODE_ENV=production myapp:1.0
+
+# Volume mount (named volume)
+docker run -v mydata:/app/data myapp:1.0
+
+# Bind mount (development)
+docker run -v $(pwd)/src:/app/src myapp:1.0
+
+# Resource limits
+docker run --memory 512m --cpus 0.5 myapp:1.0
+
+# Interactive terminal
+docker run -it myapp:1.0 /bin/sh
+```
+
+## Container Management
+
+```bash
+# List containers
+docker ps
+docker ps -a
+
+# Logs
+docker logs myapp
+docker logs -f myapp          # Follow
+docker logs --tail 100 myapp  # Last 100 lines
+
+# Execute command
+docker exec myapp ls /app
+docker exec -it myapp /bin/sh  # Interactive shell
+
+# Stop/start
+docker stop myapp
+docker start myapp
+
+# Remove
+docker rm myapp
+docker rm -f myapp  # Force remove running
+
+# Inspect
+docker inspect myapp
+
+# Monitor resources
+docker stats myapp
+
+# Copy files
+docker cp myapp:/app/logs ./logs
+```
+
+## Volume Management
+
+```bash
+# Create volume
+docker volume create mydata
+
+# List volumes
+docker volume ls
+
+# Remove volume
+docker volume rm mydata
+
+# Remove unused volumes
+docker volume prune
+```
+
+## Network Management
+
+```bash
+# Create network
+docker network create my-network
+
+# List networks
+docker network ls
+
+# Connect container
+docker network connect my-network myapp
+
+# Disconnect
+docker network disconnect my-network myapp
+```
+
+## Language-Specific Dockerfiles
+
+### Node.js
+```dockerfile
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node
+CMD ["node", "dist/server.js"]
+```
+
+### Python
+```dockerfile
+FROM python:3.11-slim AS build
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+FROM python:3.11-slim
+WORKDIR /app
+COPY --from=build /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY . .
+RUN adduser --disabled-password appuser
+USER appuser
+CMD ["python", "app.py"]
+```
+
+### Go
+```dockerfile
+FROM golang:1.21-alpine AS build
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o main .
+
+FROM scratch
+COPY --from=build /app/main /main
+CMD ["/main"]
+```
+
+## Security Hardening
+
+```dockerfile
+# Use specific versions
+FROM node:20.11.0-alpine3.19
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Set ownership
+COPY --chown=nodejs:nodejs . .
+
+# Switch to non-root
+USER nodejs
+```
+
+## Troubleshooting
+
+### Container exits immediately
+```bash
+docker logs myapp
+docker run -it myapp /bin/sh
+docker run -it --entrypoint /bin/sh myapp
+```
+
+### Cannot connect
+```bash
+docker ps
+docker port myapp
+docker network inspect bridge
+docker inspect myapp | grep IPAddress
+```
+
+### Out of disk space
+```bash
+docker system df
+docker system prune -a
+docker volume prune
+```
+
+### Build cache issues
+```bash
+docker build --no-cache -t myapp .
+docker builder prune
+```
+
+## Best Practices
+
+- Use specific image versions, not `latest`
+- Run as non-root user
+- Multi-stage builds to minimize size
+- Implement health checks
+- Set resource limits
+- Keep images under 500MB
+- Scan for vulnerabilities: `docker scout cves myapp:1.0`
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Build | `docker build -t myapp:1.0 .` |
+| Run | `docker run -d -p 8080:3000 myapp:1.0` |
+| Logs | `docker logs -f myapp` |
+| Shell | `docker exec -it myapp /bin/sh` |
+| Stop | `docker stop myapp` |
+| Remove | `docker rm myapp` |
+| Clean | `docker system prune -a` |
+
+## Resources
+
+- Docs: https://docs.docker.com
+- Best Practices: https://docs.docker.com/develop/dev-best-practices/
+- Dockerfile Reference: https://docs.docker.com/engine/reference/builder/

package/dist/skills/devops/references/docker-compose.md

@@ -0,0 +1,292 @@
+# Docker Compose
+
+Multi-container application orchestration.
+
+## Basic Structure
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+    depends_on:
+      - db
+      - redis
+    volumes:
+      - ./src:/app/src
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: app
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    networks:
+      - app-network
+    volumes:
+      - redis_data:/data
+
+volumes:
+  postgres_data:
+  redis_data:
+
+networks:
+  app-network:
+    driver: bridge
+```
+
+## Commands
+
+```bash
+# Start services
+docker compose up
+docker compose up -d
+
+# Build images before starting
+docker compose up --build
+
+# Scale service
+docker compose up -d --scale web=3
+
+# Stop services
+docker compose down
+
+# Stop and remove volumes
+docker compose down --volumes
+
+# Logs
+docker compose logs
+docker compose logs -f web
+
+# Execute command
+docker compose exec web sh
+docker compose exec db psql -U user -d app
+
+# List services
+docker compose ps
+
+# Restart service
+docker compose restart web
+
+# Pull images
+docker compose pull
+
+# Validate
+docker compose config
+```
+
+## Environment-Specific Configs
+
+**compose.yml (base):**
+```yaml
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+**compose.override.yml (dev, auto-loaded):**
+```yaml
+services:
+  web:
+    volumes:
+      - ./src:/app/src  # Live reload
+    environment:
+      - NODE_ENV=development
+      - DEBUG=true
+    command: npm run dev
+```
+
+**compose.prod.yml (production):**
+```yaml
+services:
+  web:
+    image: registry.example.com/myapp:1.0
+    restart: always
+    environment:
+      - NODE_ENV=production
+    deploy:
+      replicas: 3
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+```
+
+**Usage:**
+```bash
+# Development (uses compose.yml + compose.override.yml)
+docker compose up
+
+# Production
+docker compose -f compose.yml -f compose.prod.yml up -d
+```
+
+## Health Checks
+
+```yaml
+services:
+  web:
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 40s
+      retries: 3
+```
+
+## Resource Limits
+
+```yaml
+services:
+  web:
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 256M
+```
+
+## Logging
+
+```yaml
+services:
+  web:
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## Environment Variables
+
+**Using .env file:**
+```bash
+# .env
+DATABASE_URL=postgresql://user:pass@db:5432/app
+API_KEY=secret
+```
+
+```yaml
+services:
+  web:
+    env_file:
+      - .env
+```
+
+## Networking
+
+Services on same network communicate via service name:
+
+```yaml
+services:
+  web:
+    depends_on:
+      - db
+    environment:
+      # Use service name as hostname
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+```
+
+## Volume Backup/Restore
+
+```bash
+# Backup
+docker compose run --rm -v app_data:/data -v $(pwd):/backup \
+  alpine tar czf /backup/backup.tar.gz /data
+
+# Restore
+docker compose run --rm -v app_data:/data -v $(pwd):/backup \
+  alpine tar xzf /backup/backup.tar.gz -C /data
+```
+
+## Common Stacks
+
+### Web + Database + Cache
+```yaml
+services:
+  web:
+    build: .
+    depends_on:
+      - db
+      - redis
+  db:
+    image: postgres:15-alpine
+  redis:
+    image: redis:7-alpine
+```
+
+### Microservices
+```yaml
+services:
+  api-gateway:
+    build: ./gateway
+  user-service:
+    build: ./services/users
+  order-service:
+    build: ./services/orders
+  rabbitmq:
+    image: rabbitmq:3-management
+```
+
+## Best Practices
+
+- Use named volumes for data persistence
+- Implement health checks for all services
+- Set restart policies for production
+- Use environment-specific compose files
+- Configure resource limits
+- Enable logging with size limits
+- Use depends_on for service ordering
+- Network isolation with custom networks
+
+## Troubleshooting
+
+```bash
+# View service logs
+docker compose logs -f service-name
+
+# Check service status
+docker compose ps
+
+# Restart specific service
+docker compose restart service-name
+
+# Rebuild service
+docker compose up --build service-name
+
+# Remove everything
+docker compose down --volumes --rmi all
+```
+
+## Resources
+
+- Docs: https://docs.docker.com/compose/
+- Compose Specification: https://docs.docker.com/compose/compose-file/
+- Best Practices: https://docs.docker.com/compose/production/