Spaces:

Hwandji
/

saap-plattform

Sleeping

# 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:

# 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

# 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

# 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:

Security Checks
- Gitleaks secret scanning
- Dependency vulnerability scanning (npm audit)
Linting & Type Checking
- ESLint (frontend)
- Ruff (backend)
- TypeScript validation
Testing
- Unit tests
- Integration tests
- Coverage reporting
Build
- Multi-architecture Docker images (amd64, arm64)
- Optimized production builds
- Image tagging (commit SHA + latest)
Push to Registry
- GitHub Container Registry (ghcr.io)
- Automatic versioning

Manual Deployment

Deploy to production:

# 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:

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

🔍 Health Checks

Backend Health Check

# 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

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

🗂️ Data Persistence

Development

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

Production

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

Backup Strategy:

# 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

# 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:

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

# 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:

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

🚨 Troubleshooting

Common Issues

1. Container won't start:

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

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

2. Database connection failed:

# 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:

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

# Restart backend
docker-compose restart backend

4. CORS errors:

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

# Restart backend
docker-compose restart backend

🔄 Update Procedure

Development

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

Production

# 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

🆘 Support

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