boki/stock-bot

Fork 0

Boki d52cfe7de2 initial wcag-ada

2025-06-28 11:11:34 -04:00

6.7 KiB

Raw Permalink Blame History

WCAG-ADA Deployment Guide

Overview

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

Local Development
Docker Deployment
Kubernetes Deployment
GitLab CI/CD
Configuration Management
Monitoring & Maintenance

Local Development

Quick Start

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

# Start all services
bun run dev

Manual Setup

Start development databases:

docker-compose -f docker-compose.dev.yml up -d

Configure environment:

cp .env.example .env
# Edit .env with your settings

Install dependencies:
```
bun install
```
Run migrations:
```
cd api && bunx prisma migrate dev
```

Start services:

# 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

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

# Or manually with docker-compose
docker-compose build

Run with Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Production Docker Deployment

Set environment variables:

export API_JWT_SECRET=your-secret-key
export DATABASE_URL=postgresql://user:pass@host:5432/db
# ... other required variables

Run with production config:

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

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

# Or manually
kubectl apply -f k8s/

Configuration

Update secrets:

# Edit k8s/secrets.yaml with your values
# Then apply
kubectl apply -f k8s/secrets.yaml -n wcag-ada

Update ingress hosts:

# Edit k8s/ingress.yaml
# Replace example.com with your domain
kubectl apply -f k8s/ingress.yaml -n wcag-ada

Scaling

# 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

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

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)

Configure environments:
- Create staging and production environments in GitLab
- Set appropriate URLs

Deployment Flow

Development:
- Push to develop branch
- Automatically builds and deploys to staging
Production:
- Merge to main branch
- Builds images automatically
- Manual approval required for production deployment

Configuration Management

Environment Variables

Key configuration variables:

# 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

Command-line arguments (highest)
Environment variables
Configuration files
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:

Metrics: Prometheus + Grafana
Logs: ELK Stack or Loki
Traces: Jaeger or Zipkin
Uptime: Uptime Kuma or Pingdom

Database Maintenance

# 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

Database migrations:

# Run migrations before deployment
kubectl run migration --rm -it --image=wcag-ada/api:latest -- bunx prisma migrate deploy

Rolling updates:

# 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

View logs:

# Kubernetes
kubectl logs -f deployment/wcag-ada-api -n wcag-ada

# Docker
docker-compose logs -f api

Debug pods:

# 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

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

Network Security:
- Use NetworkPolicies in Kubernetes
- Implement proper firewall rules
- Use TLS for all external communications
Application Security:
- Rotate JWT secrets regularly
- Use strong passwords for databases
- Implement rate limiting
- Enable CORS appropriately
Container Security:
- Run containers as non-root user
- Use minimal base images
- Scan images for vulnerabilities
- Keep dependencies updated

Support

For issues or questions:

Check application logs
Review health check endpoints
Consult error messages in dashboard
Check GitLab CI/CD pipeline status

6.7 KiB Raw Permalink Blame History