initial wcag-ada
This commit is contained in:
parent
042b8cb83a
commit
d52cfe7de2
112 changed files with 9069 additions and 0 deletions
328
apps/wcag-ada/DEPLOYMENT.md
Normal file
328
apps/wcag-ada/DEPLOYMENT.md
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue