DEPLOYMENT.md

# SAAP Deployment Guide

## 📋 Overview

This guide covers deploying SAAP (satware Autonomous Agent Platform) from development to production using Docker and GitHub Actions.

## 🚀 Deployment Strategies

### 1. Local Development

**Requirements:**
- Docker & Docker Compose
- Node.js 20+ (for frontend development)
- Python 3.10+ (for backend development)

**Setup:**

```bash
# Clone repository
git clone https://github.com/satwareAG/saap.git
cd saap

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
nano .env

# Start development environment
docker-compose up -d

# Verify services
curl http://localhost:8000/health
curl http://localhost:5173
```

**Services:**
- Backend API: http://localhost:8000
- Frontend: http://localhost:5173
- API Docs: http://localhost:8000/docs
- PostgreSQL: localhost:5432

### 2. Production Deployment

**Production Configuration:**

```bash
# Use production overlay
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

**Key Differences:**
- Optimized builds (no dev dependencies)
- Port 80 exposed (not 5173)
- Named volumes for data persistence
- Production CORS settings
- No hot reload
- Uvicorn workers: 4

## 🔐 Environment Variables

### Required Variables

```bash
# API Keys (MANDATORY)
COLOSSUS_API_KEY=your-colossus-key
OPENROUTER_API_KEY=your-openrouter-key

# Database
POSTGRES_DB=saap_db
POSTGRES_USER=saap_user
POSTGRES_PASSWORD=strong-password-here
```

### Production Variables

```bash
# Security
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=WARNING
SECRET_KEY=generate-strong-secret

# CORS (whitelist domains)
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

# Performance
WORKERS=4
```

## 🛠️ CI/CD Pipeline (GitHub Actions)

### Automated Workflow

**Triggers:**
- Push to `main` branch
- Push to `develop` branch
- Pull requests to `main`

**Stages:**

1. **Security Checks**
   - Gitleaks secret scanning
   - Dependency vulnerability scanning (npm audit)

2. **Linting & Type Checking**
   - ESLint (frontend)
   - Ruff (backend)
   - TypeScript validation

3. **Testing**
   - Unit tests
   - Integration tests
   - Coverage reporting

4. **Build**
   - Multi-architecture Docker images (amd64, arm64)
   - Optimized production builds
   - Image tagging (commit SHA + latest)

5. **Push to Registry**
   - GitHub Container Registry (ghcr.io)
   - Automatic versioning

### Manual Deployment

**Deploy to production:**

```bash
# SSH into server
ssh [email protected]

# Pull latest images
docker pull ghcr.io/satwareag/saap/backend:latest
docker pull ghcr.io/satwareag/saap/frontend:latest

# Restart services
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

## 📦 Container Registry

**Images:**
```
ghcr.io/satwareag/saap/backend:latest
ghcr.io/satwareag/saap/backend:<commit-sha>
ghcr.io/satwareag/saap/frontend:latest  
ghcr.io/satwareag/saap/frontend:<commit-sha>
```

**Authentication:**

```bash
# GitHub Personal Access Token required
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
```

## 🔍 Health Checks

### Backend Health Check

```bash
# Simple health check (Docker/Kubernetes)
curl http://localhost:8000/health

# Response
{"status":"healthy","timestamp":"2025-11-18T10:00:00"}

# Detailed health check
curl http://localhost:8000/api/v1/health

# Response
{
  "status": "healthy",
  "services": {
    "agent_manager": "active",
    "websocket": "active",
    "colossus_api": "connected"
  }
}
```

### Frontend Health Check

```bash
curl http://localhost/
# Returns Vue.js application
```

## 🗂️ Data Persistence

### Development

```yaml
volumes:
  - ./backend/logs:/app/logs          # Local logs
  - ./data/postgres:/var/lib/postgresql/data  # Local database
```

### Production

```yaml
volumes:
  postgres_data:
    driver_opts:
      device: /data/saap/postgres  # Persistent storage
  backend_logs:
    driver_opts:
      device: /data/saap/logs
```

**Backup Strategy:**

```bash
# Database backup
docker exec saap-postgres-1 pg_dump -U saap_user saap_db > backup.sql

# Restore
docker exec -i saap-postgres-1 psql -U saap_user saap_db < backup.sql
```

## 🔐 Security Best Practices

### 1. Secrets Management

**NEVER commit:**
- `.env` files
- API keys
- Database passwords
- SSL certificates

**Use:**
- GitHub Secrets for CI/CD
- Environment variables in production
- Secrets managers (HashiCorp Vault, AWS Secrets Manager)

### 2. Pre-deployment Checklist

```bash
# Security scan
gitleaks detect --source . --verbose

# Dependency audit
npm audit --audit-level=moderate
pip-audit

# Secrets in .env only
grep -r "OPENROUTER_API_KEY" . --exclude-dir=node_modules --exclude=.env
```

### 3. HTTPS Configuration

**Nginx with Let's Encrypt:**

```nginx
server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 📊 Monitoring

### Application Logs

```bash
# Backend logs
docker logs saap-backend-1 -f

# Frontend logs
docker logs saap-frontend-1 -f

# Database logs
docker logs saap-postgres-1 -f
```

### Metrics

**Health check monitoring:**

```bash
# Cron job for health monitoring
*/5 * * * * curl -f http://localhost:8000/health || systemctl restart saap
```

## 🚨 Troubleshooting

### Common Issues

**1. Container won't start:**

```bash
# Check logs
docker-compose logs backend
docker-compose logs frontend

# Rebuild without cache
docker-compose build --no-cache
```

**2. Database connection failed:**

```bash
# Verify PostgreSQL running
docker-compose ps postgres

# Check DATABASE_URL in .env
echo $DATABASE_URL

# Test connection
docker exec -it saap-postgres-1 psql -U saap_user -d saap_db
```

**3. API keys not working:**

```bash
# Verify environment variables loaded
docker exec saap-backend-1 env | grep API_KEY

# Restart backend
docker-compose restart backend
```

**4. CORS errors:**

```bash
# Update CORS_ORIGINS in .env
CORS_ORIGINS=http://localhost:5173,https://yourdomain.com

# Restart backend
docker-compose restart backend
```

## 🔄 Update Procedure

### Development

```bash
git pull origin main
docker-compose down
docker-compose build
docker-compose up -d
```

### Production

```bash
# 1. Backup database
docker exec saap-postgres-1 pg_dump -U saap_user saap_db > backup.sql

# 2. Pull new images
docker pull ghcr.io/satwareag/saap/backend:latest
docker pull ghcr.io/satwareag/saap/frontend:latest

# 3. Restart with zero downtime
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --no-deps --build backend
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --no-deps --build frontend

# 4. Verify health
curl http://localhost:8000/health
```

## 📚 Additional Resources

- [Docker Documentation](https://docs.docker.com/)
- [GitHub Actions](https://docs.github.com/en/actions)
- [FastAPI Deployment](https://fastapi.tiangolo.com/deployment/)
- [Nginx Configuration](https://nginx.org/en/docs/)

## 🆘 Support

- GitHub Issues: https://github.com/satwareAG/saap/issues
- Email: [email protected]