# WCAG-ADA Deployment Guide

## Overview

This guide covers deployment options for the WCAG-ADA Compliance Monitoring Platform.

## Table of Contents

1. [Local Development](#local-development)
2. [Docker Deployment](#docker-deployment)
3. [Kubernetes Deployment](#kubernetes-deployment)
4. [GitLab CI/CD](#gitlab-cicd)
5. [Configuration Management](#configuration-management)
6. [Monitoring & Maintenance](#monitoring--maintenance)

## Local Development

### Quick Start

```bash
# Run the setup script
./scripts/local-dev.sh

# Start all services
bun run dev
```

### Manual Setup

1. **Start development databases:**
   ```bash
   docker-compose -f docker-compose.dev.yml up -d
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

3. **Install dependencies:**
   ```bash
   bun install
   ```

4. **Run migrations:**
   ```bash
   cd api && bunx prisma migrate dev
   ```

5. **Start services:**
   ```bash
   # Terminal 1 - API
   cd api && bun run dev

   # Terminal 2 - Worker
   cd worker && bun run dev

   # Terminal 3 - Dashboard
   cd dashboard && bun run dev
   ```

## Docker Deployment

### Build Images

```bash
# Using the build script
./scripts/build-images.sh

# Or manually with docker-compose
docker-compose build
```

### Run with Docker Compose

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

### Production Docker Deployment

1. **Set environment variables:**
   ```bash
   export API_JWT_SECRET=your-secret-key
   export DATABASE_URL=postgresql://user:pass@host:5432/db
   # ... other required variables
   ```

2. **Run with production config:**
   ```bash
   docker-compose -f docker-compose.yml up -d
   ```

## Kubernetes Deployment

### Prerequisites

- Kubernetes cluster (1.24+)
- kubectl configured
- Ingress controller installed
- cert-manager (for TLS)

### Deploy to Kubernetes

```bash
# Using the deploy script
./scripts/deploy-k8s.sh

# Or manually
kubectl apply -f k8s/
```

### Configuration

1. **Update secrets:**
   ```bash
   # Edit k8s/secrets.yaml with your values
   # Then apply
   kubectl apply -f k8s/secrets.yaml -n wcag-ada
   ```

2. **Update ingress hosts:**
   ```bash
   # Edit k8s/ingress.yaml
   # Replace example.com with your domain
   kubectl apply -f k8s/ingress.yaml -n wcag-ada
   ```

### Scaling

```bash
# Scale API replicas
kubectl scale deployment wcag-ada-api --replicas=5 -n wcag-ada

# Scale Worker replicas
kubectl scale deployment wcag-ada-worker --replicas=3 -n wcag-ada
```

## GitLab CI/CD

### Setup

1. **Configure GitLab Container Registry:**
   - Enable container registry in project settings
   - Note your registry URL

2. **Add CI/CD Variables:**
   ```
   CI_REGISTRY_USER     - GitLab username
   CI_REGISTRY_PASSWORD - GitLab access token
   KUBE_URL            - Kubernetes API URL (staging)
   KUBE_TOKEN          - Kubernetes service account token (staging)
   KUBE_URL_PROD       - Kubernetes API URL (production)
   KUBE_TOKEN_PROD     - Kubernetes service account token (production)
   ```

3. **Configure environments:**
   - Create `staging` and `production` environments in GitLab
   - Set appropriate URLs

### Deployment Flow

1. **Development:**
   - Push to `develop` branch
   - Automatically builds and deploys to staging

2. **Production:**
   - Merge to `main` branch
   - Builds images automatically
   - Manual approval required for production deployment

## Configuration Management

### Environment Variables

Key configuration variables:

```bash
# Application
NODE_ENV=production
APP_NAME=wcag-ada

# API
API_PORT=3001
API_JWT_SECRET=<strong-secret>
API_CORS_ORIGIN=https://your-domain.com

# Database
DATABASE_URL=postgresql://user:password@host:5432/wcag_ada

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=<redis-password>

# Worker
WORKER_CONCURRENCY=5
WORKER_QUEUE_NAME=accessibility-scans

# Scanner
SCANNER_HEADLESS=true
SCANNER_TIMEOUT=30000
```

### Configuration Priority

1. Command-line arguments (highest)
2. Environment variables
3. Configuration files
4. Default values (lowest)

### Secrets Management

- **Development:** Use `.env` files
- **Docker:** Use environment variables or Docker secrets
- **Kubernetes:** Use Kubernetes secrets
- **Production:** Consider using:
  - HashiCorp Vault
  - AWS Secrets Manager
  - Azure Key Vault
  - GitLab CI/CD variables

## Monitoring & Maintenance

### Health Checks

All services expose health endpoints:

- API: `http://api:3001/health`
- Worker: `http://worker:3002/health`
- Dashboard: `http://dashboard:8080/health`

### Monitoring Stack

Recommended monitoring setup:

1. **Metrics:** Prometheus + Grafana
2. **Logs:** ELK Stack or Loki
3. **Traces:** Jaeger or Zipkin
4. **Uptime:** Uptime Kuma or Pingdom

### Database Maintenance

```bash
# Backup PostgreSQL
kubectl exec -it postgres-pod -n wcag-ada -- pg_dump -U wcag_user wcag_ada > backup.sql

# Backup Redis
kubectl exec -it redis-pod -n wcag-ada -- redis-cli BGSAVE
```

### Updates and Migrations

1. **Database migrations:**
   ```bash
   # Run migrations before deployment
   kubectl run migration --rm -it --image=wcag-ada/api:latest -- bunx prisma migrate deploy
   ```

2. **Rolling updates:**
   ```bash
   # Update image
   kubectl set image deployment/wcag-ada-api api=wcag-ada/api:new-version -n wcag-ada
   
   # Monitor rollout
   kubectl rollout status deployment/wcag-ada-api -n wcag-ada
   ```

### Troubleshooting

1. **View logs:**
   ```bash
   # Kubernetes
   kubectl logs -f deployment/wcag-ada-api -n wcag-ada
   
   # Docker
   docker-compose logs -f api
   ```

2. **Debug pods:**
   ```bash
   # Get pod details
   kubectl describe pod <pod-name> -n wcag-ada
   
   # Execute commands in pod
   kubectl exec -it <pod-name> -n wcag-ada -- /bin/sh
   ```

3. **Common issues:**
   - Database connection: Check DATABASE_URL and network connectivity
   - Redis connection: Verify Redis is running and accessible
   - Browser issues: Ensure Chromium dependencies are installed
   - Memory issues: Increase resource limits in Kubernetes

## Security Considerations

1. **Network Security:**
   - Use NetworkPolicies in Kubernetes
   - Implement proper firewall rules
   - Use TLS for all external communications

2. **Application Security:**
   - Rotate JWT secrets regularly
   - Use strong passwords for databases
   - Implement rate limiting
   - Enable CORS appropriately

3. **Container Security:**
   - Run containers as non-root user
   - Use minimal base images
   - Scan images for vulnerabilities
   - Keep dependencies updated

## Support

For issues or questions:
1. Check application logs
2. Review health check endpoints
3. Consult error messages in dashboard
4. Check GitLab CI/CD pipeline status