deepdebug-local-agent 0.3.18 → 1.0.3

package/docs/ENTERPRISE_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,462 @@
+# DeepDebug Local Agent - Enterprise Deployment Guide
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Deployment Options](#deployment-options)
+3. [Docker Deployment](#docker-deployment)
+4. [Kubernetes Deployment](#kubernetes-deployment)
+5. [Configuration](#configuration)
+6. [Monitoring](#monitoring)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| CPU | 1 core | 2 cores |
+| Memory | 512 MB | 2 GB |
+| Disk | 100 MB | 500 MB |
+| Network | Outbound HTTPS | Outbound HTTPS |
+
+### Network Requirements
+
+| Destination | Port | Protocol | Purpose |
+|-------------|------|----------|---------|
+| api.deepdebug.ai | 443 | HTTPS | API communication |
+
+### Credentials Required
+
+- DeepDebug Tenant ID (from dashboard)
+- API Key (from dashboard)
+
+---
+
+## Deployment Options
+
+### Option 1: Docker Compose (Recommended for most)
+
+Best for: Small to medium teams, single server deployment
+
+### Option 2: Kubernetes with Helm
+
+Best for: Large teams, existing K8s infrastructure, high availability
+
+### Option 3: Native Executable
+
+Best for: Developer workstations, quick setup
+
+---
+
+## Docker Deployment
+
+### Quick Start
+
+```bash
+# 1. Create project directory
+mkdir deepdebug-agent && cd deepdebug-agent
+
+# 2. Download docker-compose.yml
+curl -O https://raw.githubusercontent.com/deepdebug/local-agent/main/docker-compose.yml
+
+# 3. Create environment file
+cat > .env << EOF
+DEEPDEBUG_TENANT_ID=your-tenant-id
+PROJECT_PATH=/path/to/your/projects
+EOF
+
+# 4. Start the agent
+docker-compose up -d
+
+# 5. Verify it's running
+curl http://localhost:5055/health
+```
+
+### Configuration Options
+
+```yaml
+# docker-compose.yml
+environment:
+  # Required
+  - DEEPDEBUG_TENANT_ID=${DEEPDEBUG_TENANT_ID}
+  
+  # Optional
+  - DEEPDEBUG_API_URL=https://api.deepdebug.ai  # Change for on-premise
+  - LOG_LEVEL=info                               # debug, info, warn, error
+  - PORT=5055                                    # Agent port
+```
+
+### Multiple Projects
+
+```yaml
+volumes:
+  # Mount multiple project directories
+  - /home/dev/project-a:/workspace/project-a:ro
+  - /home/dev/project-b:/workspace/project-b:ro
+  - /home/dev/project-c:/workspace/project-c:ro
+```
+
+### Behind Corporate Proxy
+
+```yaml
+environment:
+  - HTTP_PROXY=http://proxy.company.com:8080
+  - HTTPS_PROXY=http://proxy.company.com:8080
+  - NO_PROXY=localhost,127.0.0.1,.company.com
+```
+
+---
+
+## Kubernetes Deployment
+
+### Prerequisites
+
+- Kubernetes 1.21+
+- Helm 3.0+
+- kubectl configured
+
+### Quick Start
+
+```bash
+# 1. Add Helm repository
+helm repo add deepdebug https://charts.deepdebug.ai
+helm repo update
+
+# 2. Create namespace
+kubectl create namespace deepdebug
+
+# 3. Create secret with tenant ID
+kubectl create secret generic deepdebug-credentials \
+  --namespace deepdebug \
+  --from-literal=tenant-id=your-tenant-id
+
+# 4. Install the chart
+helm install deepdebug-agent deepdebug/deepdebug-agent \
+  --namespace deepdebug \
+  --set config.tenantId=your-tenant-id
+
+# 5. Verify deployment
+kubectl get pods -n deepdebug
+```
+
+### Custom Values
+
+```yaml
+# values-production.yaml
+replicaCount: 2
+
+resources:
+  limits:
+    cpu: "2"
+    memory: "2Gi"
+  requests:
+    cpu: "500m"
+    memory: "512Mi"
+
+config:
+  tenantId: "your-tenant-id"
+  apiUrl: "https://api.deepdebug.ai"
+  logLevel: "info"
+
+# Mount code from NFS
+volumes:
+  workspace:
+    enabled: true
+    nfs:
+      server: nfs.company.com
+      path: /exports/projects
+
+# Network policy for security
+networkPolicy:
+  enabled: true
+```
+
+Install with custom values:
+
+```bash
+helm install deepdebug-agent deepdebug/deepdebug-agent \
+  --namespace deepdebug \
+  -f values-production.yaml
+```
+
+### OpenShift Deployment
+
+```yaml
+# Additional SecurityContextConstraints for OpenShift
+securityContext:
+  runAsNonRoot: true
+  runAsUser: null  # Let OpenShift assign
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DEEPDEBUG_TENANT_ID` | Yes | - | Your tenant identifier |
+| `DEEPDEBUG_API_URL` | No | https://api.deepdebug.ai | API endpoint |
+| `DEEPDEBUG_WORKSPACE_PATH` | No | /workspace | Path to mounted projects |
+| `PORT` | No | 5055 | Agent listening port |
+| `LOG_LEVEL` | No | info | Logging verbosity |
+| `NODE_ENV` | No | production | Environment mode |
+
+### Configuration File (Optional)
+
+```yaml
+# config.yaml
+tenant:
+  id: your-tenant-id
+  
+api:
+  url: https://api.deepdebug.ai
+  timeout: 30000
+  
+workspace:
+  path: /workspace
+  exclude:
+    - node_modules
+    - .git
+    - target
+    - build
+    
+logging:
+  level: info
+  format: json
+```
+
+Mount the config file:
+
+```yaml
+volumes:
+  - ./config.yaml:/app/config.yaml:ro
+environment:
+  - CONFIG_PATH=/app/config.yaml
+```
+
+---
+
+## Monitoring
+
+### Health Endpoint
+
+```bash
+# Check health
+curl http://localhost:5055/health
+
+# Response
+{
+  "status": "healthy",
+  "version": "1.0.0",
+  "uptime": 3600
+}
+```
+
+### Prometheus Metrics
+
+```bash
+# Metrics endpoint
+curl http://localhost:5055/metrics
+```
+
+Available metrics:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `deepdebug_requests_total` | Counter | Total API requests |
+| `deepdebug_errors_total` | Counter | Total errors |
+| `deepdebug_analysis_duration_seconds` | Histogram | Analysis duration |
+| `deepdebug_workspace_files_total` | Gauge | Files in workspace |
+
+### Grafana Dashboard
+
+Import dashboard ID: `XXXXX` (coming soon)
+
+### Alerts
+
+```yaml
+# prometheus-alerts.yaml
+groups:
+  - name: deepdebug
+    rules:
+      - alert: DeepDebugAgentDown
+        expr: up{job="deepdebug-agent"} == 0
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "DeepDebug Agent is down"
+          
+      - alert: DeepDebugHighErrorRate
+        expr: rate(deepdebug_errors_total[5m]) > 0.1
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High error rate in DeepDebug Agent"
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Agent won't start
+
+```bash
+# Check logs
+docker logs deepdebug-agent
+
+# Common causes:
+# 1. Missing DEEPDEBUG_TENANT_ID
+# 2. Cannot reach api.deepdebug.ai
+# 3. Port 5055 already in use
+```
+
+#### Cannot connect to API
+
+```bash
+# Test connectivity
+curl -v https://api.deepdebug.ai/health
+
+# Check proxy settings
+echo $HTTP_PROXY
+echo $HTTPS_PROXY
+```
+
+#### Permission denied on workspace
+
+```bash
+# Check mount permissions
+ls -la /workspace
+
+# Ensure container user can read
+# The container runs as UID 1001
+chown -R 1001:1001 /path/to/projects  # If needed
+```
+
+#### High memory usage
+
+```bash
+# Check container resources
+docker stats deepdebug-agent
+
+# Increase memory limit if needed
+# In docker-compose.yml:
+deploy:
+  resources:
+    limits:
+      memory: 4G
+```
+
+### Debug Mode
+
+Enable debug logging:
+
+```yaml
+environment:
+  - LOG_LEVEL=debug
+```
+
+### Support
+
+- Documentation: https://docs.deepdebug.ai
+- Email: support@deepdebug.ai
+- Enterprise support: enterprise@deepdebug.ai
+
+---
+
+## Appendix
+
+### A. Sample docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  deepdebug-agent:
+    image: deepdebug/local-agent:1.0.0
+    container_name: deepdebug-agent
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    ports:
+      - "127.0.0.1:5055:5055"
+    volumes:
+      - ${PROJECT_PATH}:/workspace:ro
+      - agent-tmp:/tmp
+    environment:
+      - DEEPDEBUG_TENANT_ID=${DEEPDEBUG_TENANT_ID}
+      - DEEPDEBUG_API_URL=${DEEPDEBUG_API_URL:-https://api.deepdebug.ai}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5055/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+volumes:
+  agent-tmp:
+```
+
+### B. Kubernetes Manifest (without Helm)
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deepdebug-agent
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: deepdebug-agent
+  template:
+    metadata:
+      labels:
+        app: deepdebug-agent
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1001
+      containers:
+        - name: agent
+          image: deepdebug/local-agent:1.0.0
+          ports:
+            - containerPort: 5055
+          env:
+            - name: DEEPDEBUG_TENANT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: deepdebug-credentials
+                  key: tenant-id
+          resources:
+            limits:
+              cpu: "2"
+              memory: "2Gi"
+            requests:
+              cpu: "500m"
+              memory: "512Mi"
+          securityContext:
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: deepdebug-agent
+spec:
+  selector:
+    app: deepdebug-agent
+  ports:
+    - port: 5055
+      targetPort: 5055
+```

package/docs/QUICKSTART.md

@@ -0,0 +1,193 @@
+# DeepDebug Local Agent - Quick Start Guide
+
+## 🚀 Get Started in 2 Minutes
+
+### Step 1: Download
+
+Download the agent for your operating system:
+
+| Platform | Download |
+|----------|----------|
+| 🪟 Windows | [deepdebug-agent-windows.exe](https://downloads.deepdebug.ai/agent/latest/windows) |
+| 🍎 macOS (Intel) | [deepdebug-agent-macos-x64](https://downloads.deepdebug.ai/agent/latest/macos-x64) |
+| 🍎 macOS (Apple Silicon) | [deepdebug-agent-macos-arm64](https://downloads.deepdebug.ai/agent/latest/macos-arm64) |
+| 🐧 Linux | [deepdebug-agent-linux](https://downloads.deepdebug.ai/agent/latest/linux) |
+
+### Step 2: Run
+
+#### Windows
+
+```powershell
+# Open PowerShell and run:
+.\deepdebug-agent-windows.exe --tenant-id YOUR_TENANT_ID --workspace "C:\path\to\your\project"
+```
+
+#### macOS / Linux
+
+```bash
+# Make executable
+chmod +x deepdebug-agent-macos
+
+# Run
+./deepdebug-agent-macos --tenant-id YOUR_TENANT_ID --workspace /path/to/your/project
+```
+
+### Step 3: Verify
+
+Open your browser: http://localhost:5055/health
+
+You should see:
+```json
+{"status": "healthy", "version": "1.0.0"}
+```
+
+---
+
+## 📋 Command Line Options
+
+```
+deepdebug-agent [options]
+
+Options:
+  --tenant-id <id>      Your DeepDebug tenant ID (required)
+  --workspace <path>    Path to your project (required)
+  --port <number>       Port to listen on (default: 5055)
+  --api-url <url>       DeepDebug API URL (default: https://api.deepdebug.ai)
+  --log-level <level>   Log level: debug, info, warn, error (default: info)
+  --help                Show help
+  --version             Show version
+```
+
+---
+
+## 💡 Examples
+
+### Single Project
+
+```bash
+./deepdebug-agent \
+  --tenant-id abc123 \
+  --workspace /home/dev/my-project
+```
+
+### Multiple Projects
+
+```bash
+./deepdebug-agent \
+  --tenant-id abc123 \
+  --workspace /home/dev/project-a \
+  --workspace /home/dev/project-b
+```
+
+### With Debug Logging
+
+```bash
+./deepdebug-agent \
+  --tenant-id abc123 \
+  --workspace /home/dev/my-project \
+  --log-level debug
+```
+
+---
+
+## 🔧 Run as Background Service
+
+### macOS (launchd)
+
+```bash
+# Create service file
+cat > ~/Library/LaunchAgents/com.deepdebug.agent.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.deepdebug.agent</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/deepdebug-agent</string>
+        <string>--tenant-id</string>
+        <string>YOUR_TENANT_ID</string>
+        <string>--workspace</string>
+        <string>/path/to/your/project</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+EOF
+
+# Load service
+launchctl load ~/Library/LaunchAgents/com.deepdebug.agent.plist
+```
+
+### Linux (systemd)
+
+```bash
+# Create service file
+sudo cat > /etc/systemd/system/deepdebug-agent.service << EOF
+[Unit]
+Description=DeepDebug Local Agent
+After=network.target
+
+[Service]
+Type=simple
+User=$USER
+ExecStart=/usr/local/bin/deepdebug-agent --tenant-id YOUR_TENANT_ID --workspace /path/to/project
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Enable and start
+sudo systemctl enable deepdebug-agent
+sudo systemctl start deepdebug-agent
+
+# Check status
+sudo systemctl status deepdebug-agent
+```
+
+### Windows (as Service)
+
+```powershell
+# Using NSSM (Non-Sucking Service Manager)
+# Download from: https://nssm.cc/
+
+nssm install DeepDebugAgent "C:\path\to\deepdebug-agent.exe"
+nssm set DeepDebugAgent AppParameters "--tenant-id YOUR_TENANT_ID --workspace C:\path\to\project"
+nssm start DeepDebugAgent
+```
+
+---
+
+## ❓ FAQ
+
+### Where do I get my Tenant ID?
+
+1. Log in to https://app.deepdebug.ai
+2. Go to Settings → Organization
+3. Copy your Tenant ID
+
+### Is my code sent to the cloud?
+
+Only small code snippets (error locations) are sent for analysis. Your full codebase never leaves your machine. See our [Security Whitepaper](SECURITY_WHITEPAPER.md) for details.
+
+### Can I use it offline?
+
+The agent requires internet connectivity to communicate with the DeepDebug API. For air-gapped environments, contact us about on-premise deployment.
+
+### How do I update?
+
+Simply download the latest version and replace the executable. Your configuration is preserved.
+
+---
+
+## 🆘 Need Help?
+
+- 📚 Documentation: https://docs.deepdebug.ai
+- 💬 Community: https://community.deepdebug.ai
+- 📧 Support: support@deepdebug.ai