328 lines
No EOL
6.7 KiB
Markdown
328 lines
No EOL
6.7 KiB
Markdown
# 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 |