lynkr 3.3.1 → 4.1.0

package/documentation/docker.md

@@ -0,0 +1,867 @@
+# Docker Deployment Guide
+
+Complete guide to deploying Lynkr with Docker and docker-compose, including GPU support and Kubernetes deployment.
+
+---
+
+## Quick Start
+
+### docker-compose (Recommended)
+
+**1. Clone repository:**
+```bash
+git clone https://github.com/vishalveerareddy123/Lynkr.git
+cd Lynkr
+```
+
+**2. Configure environment:**
+```bash
+cp .env.example .env
+# Edit .env with your provider credentials
+```
+
+**3. Start services:**
+```bash
+docker-compose up -d
+```
+
+**4. Verify:**
+```bash
+curl http://localhost:8081/health/live
+# Expected: {"status":"ok"}
+```
+
+---
+
+## Docker Compose Configuration
+
+### Standard Setup (docker-compose.yml)
+
+```yaml
+version: '3.8'
+
+services:
+  lynkr:
+    build: .
+    container_name: lynkr
+    ports:
+      - "8081:8081"  # Lynkr proxy
+    env_file:
+      - .env
+    volumes:
+      - ./data:/app/data              # Persistent data (memories, sessions)
+      - ./workspace:/app/workspace    # Workspace for file operations
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8081/health/live"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+```
+
+### With Ollama (Local LLM)
+
+```yaml
+version: '3.8'
+
+services:
+  # Lynkr proxy
+  lynkr:
+    build: .
+    container_name: lynkr
+    ports:
+      - "8081:8081"
+    environment:
+      # Hybrid routing: Ollama first, fallback to cloud
+      - MODEL_PROVIDER=ollama
+      - OLLAMA_API_BASE=http://ollama:11434
+      - PREFER_OLLAMA=true
+      - FALLBACK_ENABLED=true
+      - FALLBACK_PROVIDER=databricks
+      - DATABRICKS_API_BASE=${DATABRICKS_API_BASE}
+      - DATABRICKS_API_KEY=${DATABRICKS_API_KEY}
+    volumes:
+      - ./data:/app/data
+      - ./workspace:/app/workspace
+    depends_on:
+      - ollama
+    restart: unless-stopped
+
+  # Ollama local LLM server
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  ollama_data:
+```
+
+**Pull models:**
+```bash
+# Enter Ollama container
+docker exec -it ollama ollama pull qwen2.5-coder:7b
+
+# Or from host (if Ollama CLI installed)
+ollama pull qwen2.5-coder:7b
+```
+
+### With GPU Support (NVIDIA)
+
+```yaml
+version: '3.8'
+
+services:
+  lynkr:
+    build: .
+    container_name: lynkr
+    ports:
+      - "8081:8081"
+    environment:
+      - MODEL_PROVIDER=ollama
+      - OLLAMA_API_BASE=http://ollama:11434
+    volumes:
+      - ./data:/app/data
+      - ./workspace:/app/workspace
+    depends_on:
+      - ollama
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]
+    restart: unless-stopped
+
+volumes:
+  ollama_data:
+```
+
+**Prerequisites:**
+1. Install NVIDIA drivers
+2. Install NVIDIA Container Toolkit:
+```bash
+# Ubuntu/Debian
+distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
+curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
+curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
+  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
+
+sudo apt-get update
+sudo apt-get install -y nvidia-container-toolkit
+sudo systemctl restart docker
+```
+
+**Verify GPU access:**
+```bash
+docker exec -it ollama nvidia-smi
+```
+
+### With Embeddings (for Cursor @Codebase)
+
+```yaml
+version: '3.8'
+
+services:
+  lynkr:
+    build: .
+    container_name: lynkr
+    ports:
+      - "8081:8081"
+    environment:
+      - MODEL_PROVIDER=databricks
+      - DATABRICKS_API_BASE=${DATABRICKS_API_BASE}
+      - DATABRICKS_API_KEY=${DATABRICKS_API_KEY}
+
+      # Embeddings via Ollama
+      - EMBEDDINGS_PROVIDER=ollama
+      - OLLAMA_API_BASE=http://ollama:11434
+      - OLLAMA_EMBEDDINGS_MODEL=nomic-embed-text
+
+      # Index workspace for @Codebase
+      - WORKSPACE_ROOT=/app/workspace
+      - WORKSPACE_INDEX_ENABLED=true
+    volumes:
+      - ./data:/app/data
+      - ./workspace:/app/workspace
+    depends_on:
+      - ollama
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  ollama_data:
+```
+
+**Pull embedding model:**
+```bash
+docker exec -it ollama ollama pull nomic-embed-text
+```
+
+---
+
+## Standalone Docker
+
+### Build Image
+
+```bash
+# Build from Dockerfile
+docker build -t lynkr:latest .
+
+# Or pull from registry (when available)
+docker pull ghcr.io/vishalveerareddy123/lynkr:latest
+```
+
+### Run Container
+
+**With Databricks:**
+```bash
+docker run -d \
+  --name lynkr \
+  -p 8081:8081 \
+  -e MODEL_PROVIDER=databricks \
+  -e DATABRICKS_API_BASE=https://your-workspace.databricks.com \
+  -e DATABRICKS_API_KEY=your-key \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/workspace:/app/workspace \
+  --restart unless-stopped \
+  lynkr:latest
+```
+
+**With Ollama:**
+```bash
+# Start Ollama first
+docker run -d \
+  --name ollama \
+  -p 11434:11434 \
+  -v ollama_data:/root/.ollama \
+  ollama/ollama:latest
+
+# Start Lynkr
+docker run -d \
+  --name lynkr \
+  -p 8081:8081 \
+  -e MODEL_PROVIDER=ollama \
+  -e OLLAMA_API_BASE=http://ollama:11434 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/workspace:/app/workspace \
+  --link ollama \
+  --restart unless-stopped \
+  lynkr:latest
+```
+
+**With AWS Bedrock:**
+```bash
+docker run -d \
+  --name lynkr \
+  -p 8081:8081 \
+  -e MODEL_PROVIDER=bedrock \
+  -e AWS_ACCESS_KEY_ID=AKIA... \
+  -e AWS_SECRET_ACCESS_KEY=... \
+  -e AWS_BEDROCK_REGION=us-east-1 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/workspace:/app/workspace \
+  --restart unless-stopped \
+  lynkr:latest
+```
+
+---
+
+## Dockerfile
+
+### Standard Dockerfile
+
+```dockerfile
+# Use Node.js 18 Alpine for smaller image
+FROM node:18-alpine
+
+# Set working directory
+WORKDIR /app
+
+# Install dependencies
+COPY package*.json ./
+RUN npm ci --production
+
+# Copy application code
+COPY . .
+
+# Create data directories
+RUN mkdir -p /app/data /app/workspace
+
+# Expose port
+EXPOSE 8081
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:8081/health/live', (r) => { process.exit(r.statusCode === 200 ? 0 : 1); })"
+
+# Run as non-root user
+USER node
+
+# Start application
+CMD ["node", "index.js"]
+```
+
+### Multi-stage Dockerfile (Smaller Image)
+
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+
+# Runtime stage
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy dependencies
+COPY --from=builder /app/node_modules ./node_modules
+
+# Copy application
+COPY . .
+
+# Create directories
+RUN mkdir -p /app/data /app/workspace && \
+    chown -R node:node /app
+
+# Expose port
+EXPOSE 8081
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:8081/health/live', (r) => { process.exit(r.statusCode === 200 ? 0 : 1); })"
+
+# Run as non-root user
+USER node
+
+CMD ["node", "index.js"]
+```
+
+---
+
+## Volume Management
+
+### Persistent Data
+
+**Required volumes:**
+```yaml
+volumes:
+  - ./data:/app/data              # SQLite databases (memories, sessions)
+  - ./workspace:/app/workspace    # File operations workspace
+```
+
+**Data directory structure:**
+```
+data/
+  ├── memories.db           # Long-term memory database
+  ├── sessions.db           # Conversation history
+  └── workspace-index.db    # Workspace metadata
+```
+
+### Backup Data
+
+**Backup script:**
+```bash
+#!/bin/bash
+# backup-lynkr.sh
+
+BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
+mkdir -p $BACKUP_DIR
+
+# Stop container
+docker-compose stop lynkr
+
+# Backup data
+cp -r ./data $BACKUP_DIR/
+cp -r ./workspace $BACKUP_DIR/
+
+# Restart container
+docker-compose start lynkr
+
+echo "Backup saved to: $BACKUP_DIR"
+```
+
+### Restore Data
+
+```bash
+#!/bin/bash
+# restore-lynkr.sh
+
+BACKUP_DIR=$1
+
+if [ -z "$BACKUP_DIR" ]; then
+  echo "Usage: ./restore-lynkr.sh <backup_directory>"
+  exit 1
+fi
+
+# Stop container
+docker-compose stop lynkr
+
+# Restore data
+rm -rf ./data ./workspace
+cp -r $BACKUP_DIR/data ./
+cp -r $BACKUP_DIR/workspace ./
+
+# Restart container
+docker-compose start lynkr
+
+echo "Restored from: $BACKUP_DIR"
+```
+
+---
+
+## Environment Variables
+
+### Core Configuration
+
+```yaml
+environment:
+  # Provider
+  - MODEL_PROVIDER=databricks
+  - DATABRICKS_API_BASE=https://your-workspace.databricks.com
+  - DATABRICKS_API_KEY=${DATABRICKS_API_KEY}
+
+  # Hybrid routing
+  - PREFER_OLLAMA=true
+  - FALLBACK_ENABLED=true
+  - FALLBACK_PROVIDER=databricks
+
+  # Port
+  - PORT=8081
+
+  # Logging
+  - LOG_LEVEL=info
+
+  # Memory
+  - MEMORY_ENABLED=true
+  - MEMORY_RETRIEVAL_LIMIT=5
+
+  # Caching
+  - PROMPT_CACHE_ENABLED=true
+  - PROMPT_CACHE_TTL_MS=300000
+```
+
+### Security Configuration
+
+```yaml
+environment:
+  # Git policies
+  - POLICY_GIT_ALLOW_PUSH=false
+  - POLICY_GIT_REQUIRE_TESTS=true
+  - POLICY_GIT_TEST_COMMAND=npm test
+
+  # Web fetch policies
+  - WEB_SEARCH_ALLOWED_HOSTS=github.com,stackoverflow.com
+
+  # Workspace policies
+  - WORKSPACE_ROOT=/app/workspace
+  - POLICY_MAX_STEPS=8
+
+  # MCP sandbox
+  - MCP_SANDBOX_ENABLED=true
+  - MCP_SANDBOX_IMAGE=ubuntu:22.04
+```
+
+---
+
+## Docker Commands
+
+### Container Management
+
+```bash
+# Start services
+docker-compose up -d
+
+# Stop services
+docker-compose stop
+
+# Restart services
+docker-compose restart
+
+# View logs
+docker-compose logs -f lynkr
+
+# View logs (last 100 lines)
+docker-compose logs --tail=100 lynkr
+
+# Execute command in container
+docker-compose exec lynkr sh
+
+# Remove containers
+docker-compose down
+
+# Remove containers and volumes
+docker-compose down -v
+```
+
+### Debugging
+
+```bash
+# Check container status
+docker-compose ps
+
+# Inspect container
+docker inspect lynkr
+
+# Check resource usage
+docker stats lynkr
+
+# View container logs
+docker logs -f lynkr
+
+# Enter container shell
+docker exec -it lynkr sh
+
+# Check environment variables
+docker exec lynkr env
+
+# Test health endpoint
+docker exec lynkr curl http://localhost:8081/health/live
+```
+
+---
+
+## Kubernetes Deployment
+
+### Basic Deployment
+
+**deployment.yaml:**
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: lynkr
+  labels:
+    app: lynkr
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: lynkr
+  template:
+    metadata:
+      labels:
+        app: lynkr
+    spec:
+      containers:
+      - name: lynkr
+        image: ghcr.io/vishalveerareddy123/lynkr:latest
+        ports:
+        - containerPort: 8081
+          name: http
+        env:
+        - name: MODEL_PROVIDER
+          value: "databricks"
+        - name: DATABRICKS_API_BASE
+          valueFrom:
+            secretKeyRef:
+              name: lynkr-secrets
+              key: databricks-api-base
+        - name: DATABRICKS_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: lynkr-secrets
+              key: databricks-api-key
+        resources:
+          requests:
+            cpu: "500m"
+            memory: "512Mi"
+          limits:
+            cpu: "2"
+            memory: "2Gi"
+        volumeMounts:
+        - name: data
+          mountPath: /app/data
+        - name: workspace
+          mountPath: /app/workspace
+        livenessProbe:
+          httpGet:
+            path: /health/live
+            port: 8081
+          initialDelaySeconds: 10
+          periodSeconds: 10
+          timeoutSeconds: 5
+          failureThreshold: 3
+        readinessProbe:
+          httpGet:
+            path: /health/ready
+            port: 8081
+          initialDelaySeconds: 5
+          periodSeconds: 5
+          timeoutSeconds: 3
+          failureThreshold: 3
+      volumes:
+      - name: data
+        persistentVolumeClaim:
+          claimName: lynkr-data-pvc
+      - name: workspace
+        persistentVolumeClaim:
+          claimName: lynkr-workspace-pvc
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: lynkr
+  labels:
+    app: lynkr
+spec:
+  selector:
+    app: lynkr
+  ports:
+  - port: 80
+    targetPort: 8081
+    protocol: TCP
+    name: http
+  type: LoadBalancer
+```
+
+**secrets.yaml:**
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: lynkr-secrets
+type: Opaque
+stringData:
+  databricks-api-base: "https://your-workspace.databricks.com"
+  databricks-api-key: "your-api-key"
+```
+
+**persistent-volumes.yaml:**
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: lynkr-data-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: lynkr-workspace-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 50Gi
+```
+
+**Deploy:**
+```bash
+# Create secrets
+kubectl apply -f secrets.yaml
+
+# Create PVCs
+kubectl apply -f persistent-volumes.yaml
+
+# Deploy application
+kubectl apply -f deployment.yaml
+
+# Check status
+kubectl get pods -l app=lynkr
+kubectl get svc lynkr
+
+# View logs
+kubectl logs -f deployment/lynkr
+
+# Scale replicas
+kubectl scale deployment/lynkr --replicas=5
+```
+
+---
+
+## Production Best Practices
+
+### Security
+
+1. **Run as non-root user:**
+```dockerfile
+USER node
+```
+
+2. **Read-only root filesystem:**
+```yaml
+security_opt:
+  - no-new-privileges:true
+read_only: true
+tmpfs:
+  - /tmp
+```
+
+3. **Resource limits:**
+```yaml
+deploy:
+  resources:
+    limits:
+      cpus: '2'
+      memory: 2G
+    reservations:
+      cpus: '0.5'
+      memory: 512M
+```
+
+### Monitoring
+
+1. **Prometheus metrics:**
+```yaml
+# Expose metrics port
+ports:
+  - "8081:8081"  # Main port (includes /metrics)
+```
+
+2. **Health checks:**
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:8081/health/live"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 40s
+```
+
+3. **Logging:**
+```yaml
+logging:
+  driver: "json-file"
+  options:
+    max-size: "10m"
+    max-file: "3"
+```
+
+### High Availability
+
+1. **Multiple replicas:**
+```yaml
+spec:
+  replicas: 3
+```
+
+2. **Load balancer:**
+```yaml
+services:
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      - lynkr
+```
+
+3. **Shared database:**
+```yaml
+volumes:
+  - lynkr_data:/app/data  # Shared volume
+
+volumes:
+  lynkr_data:
+    driver: local
+```
+
+---
+
+## Troubleshooting
+
+### Container Won't Start
+
+```bash
+# Check logs
+docker-compose logs lynkr
+
+# Common issues:
+# 1. Missing environment variables
+# 2. Invalid API credentials
+# 3. Port already in use
+```
+
+### Connection Refused
+
+```bash
+# Check container is running
+docker-compose ps
+
+# Check port binding
+docker port lynkr
+
+# Test from inside container
+docker exec lynkr curl http://localhost:8081/health/live
+```
+
+### Out of Memory
+
+```bash
+# Increase memory limit
+docker-compose.yml:
+  deploy:
+    resources:
+      limits:
+        memory: 4G  # Increase from 2G
+```
+
+### Slow Performance
+
+```bash
+# Check resource usage
+docker stats lynkr
+
+# Increase CPU limit
+docker-compose.yml:
+  deploy:
+    resources:
+      limits:
+        cpus: '4'  # Increase from 2
+```
+
+---
+
+## Next Steps
+
+- **[Production Guide](production.md)** - Production deployment best practices
+- **[Monitoring Guide](production.md#monitoring)** - Prometheus + Grafana setup
+- **[API Reference](api.md)** - API endpoints
+- **[Troubleshooting](troubleshooting.md)** - Common issues
+
+---
+
+## Getting Help
+
+- **[GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions)** - Ask questions
+- **[GitHub Issues](https://github.com/vishalveerareddy123/Lynkr/issues)** - Report issues