Skip to content

Latest commit

 

History

History
298 lines (232 loc) · 8.87 KB

DOCKER-K8S-SETUP.md

File metadata and controls

298 lines (232 loc) · 8.87 KB

🎉 Docker + Kubernetes + Cypress Setup Complete!

✅ What Was Created

🐳 Docker Files

  1. backend/Dockerfile - Production-ready Python backend with:

    • Multi-stage build optimization
    • Non-root user for security
    • Health checks
    • 4 Uvicorn workers for performance

  2. frontend/Dockerfile - Optimized React frontend with:

    • Multi-stage build (Node build → Nginx serve)
    • Gzip compression
    • Security headers
    • Health check endpoint

  3. docker-compose.yml - Local development orchestration:

    • Backend + Frontend + Cypress services
    • Health check dependencies
    • Test profile for on-demand Cypress runs
    • Isolated network

  4. .dockerignore files - Faster builds by excluding unnecessary files

☸️ Kubernetes Manifests (k8s/ directory)

  1. namespace.yaml - Dedicated namespace with SDG labels
  2. configmap.yaml - Environment configurations
  3. backend-deployment.yaml - 3-replica backend with autoscaling
  4. frontend-deployment.yaml - 2-replica frontend with load balancing
  5. hpa.yaml - Horizontal Pod Autoscaler (CPU/memory-based)
  6. cypress-job.yaml - E2E testing job with init containers
  7. ingress.yaml - NGINX ingress with TLS and rate limiting

🧪 Cypress E2E Tests

  1. cypress.config.js - Test configuration

  2. cypress/e2e/lgbtq-analysis.cy.js - Comprehensive test suite:

    • Homepage & language toggle (8 tests)
    • Survey form interaction (3 tests)
    • Results display & validation (3 tests)
    • English translation verification (1 test)
    • Reset functionality (1 test)
    • API integration (1 test)
    • Responsive design (2 tests)
    • Total: 19 automated tests

  3. cypress/support/ - Custom commands and utilities

📚 Documentation

  1. DEPLOYMENT.md - Comprehensive 300+ line deployment guide
  2. deploy.ps1 - Interactive PowerShell deployment script

🚀 Quick Start Commands

Option 1: Docker Compose (Easiest)

# Start everything
docker-compose up -d

# Access:
# Frontend: http://localhost:3000
# Backend: http://localhost:8000

Option 2: With Cypress Tests

# Run automated tests
docker-compose --profile test up

Option 3: Kubernetes

# Use interactive script
.\deploy.ps1

# Or manual deployment
kubectl apply -f k8s/
kubectl port-forward svc/frontend-service 3000:80 -n lgbtq-analysis

Option 4: Local Cypress Development

cd frontend
npm install cypress
npm run cy:open  # Interactive UI
npm run cy:run   # Headless mode

🎯 Why This Architecture?

Kubernetes Benefits:

  1. 🚀 High Availability

    • 3 backend replicas + 2 frontend replicas
    • Automatic failover
    • Zero-downtime deployments (RollingUpdate strategy)

  2. 📈 Auto-Scaling

    • Scales 3-10 backend pods based on CPU (70% threshold)
    • Scales 2-5 frontend pods based on load
    • Handles traffic spikes during research campaigns

  3. 🔒 Security

    • RunAsNonRoot (UIDs 1000/101)
    • No privilege escalation
    • ReadOnlyRootFilesystem where possible
    • Network policies for isolation

  4. 🌐 Privacy-First

    • No persistent volumes (in-memory processing only)
    • ConfigMaps for bilingual settings
    • Complies with GDPR/ISO privacy standards

  5. ♿ Accessibility (SDG Alignment)

    • SDG 3: High availability ensures mental health resources access
    • SDG 5: Inclusive design for all gender identities
    • SDG 10: Bilingual Thai/English reduces language barriers

Cypress Benefits:

  1. ✅ Comprehensive Coverage

    • Tests real user workflows (not just unit tests)
    • Validates bilingual functionality
    • Ensures privacy compliance (no data persistence)
    • Cross-browser testing (Chrome, Firefox, Edge)

  2. 🔍 Visual Debugging

    • Video recordings of test runs
    • Screenshots on failure
    • Time-travel debugging

  3. ⚙️ CI/CD Ready

    • Runs in Docker containers
    • Kubernetes Job execution
    • GitHub Actions integration

  4. 🎨 Developer Experience

    • Fast test execution
    • Clear error messages
    • Real-time browser interaction

📊 Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                 🌍 Internet Traffic                      │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │ Ingress │ (NGINX + TLS + Rate Limiting)
                    └────┬────┘
              ┌──────────┴──────────┐
              │                     │
       ┌──────▼──────┐      ┌──────▼──────┐
       │  Frontend   │      │   Backend   │
       │  Service    │      │   Service   │
       │ LoadBalancer│      │  ClusterIP  │
       └──────┬──────┘      └──────┬──────┘
              │                    │
    ┌─────────┼─────────┐   ┌──────┼──────┐
    │         │         │   │      │      │
┌───▼──┐  ┌──▼──┐  ┌───▼───▼──┐ ┌─▼──┐ ┌─▼──┐
│Nginx │  │Nginx│  │ Uvicorn │ │Uvic││Uvic│
│Pod 1 │  │Pod 2│  │  Pod 1  │ │n 2 ││n 3 │
└──────┘  └─────┘  └─────────┘ └────┘└────┘
                         │
                    ┌────▼────┐
                    │   HPA   │ (Auto-scaling 3-10 pods)
                    └─────────┘
                         
                    ┌─────────┐
                    │ Cypress │ (E2E Testing Job)
                    │  Tests  │ (19 automated tests)
                    └─────────┘

🧪 Test Coverage

Cypress E2E Tests (19 tests):

✅ Homepage & Language Toggle (8 tests)

  • Page loads successfully
  • Privacy badges display (🔒 No data, 🧠 Statistical, 🎓 Educational, 🌍 SDG)
  • Thai → English → Thai language switching
  • Header translations

✅ Survey Form (3 tests)

  • All 6 question groups render
  • Radio button selection
  • Submit/Reset buttons

✅ Results Display (3 tests)

  • Overall score calculation (0-100%)
  • 6 section scores with emojis (📺📱👨‍👩‍👧💻🌏🔍🏫)
  • Disclaimer and academic references

✅ English Translation (1 test)

  • Results display correctly in English
  • Insights translated ("Minimal level of openness...")

✅ Reset Functionality (1 test)

  • Form clears all selections

✅ API Integration (1 test)

  • POST /api/v1/analysis returns 200
  • Request/response validation

✅ Responsive Design (2 tests)

  • Mobile viewport (iPhone X)
  • Tablet viewport (iPad)

📦 Resource Requirements

Development (Docker Compose):

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 2GB

Production (Kubernetes):

  • Backend: 256Mi-512Mi RAM, 250m-500m CPU (per pod)
  • Frontend: 128Mi-256Mi RAM, 100m-200m CPU (per pod)
  • Cypress: 1Gi-2Gi RAM, 500m-1000m CPU (during tests)
  • Total: ~3GB RAM, 2 CPU cores (minimum)

🔧 Customization

Change Replica Counts:

# k8s/backend-deployment.yaml
spec:
  replicas: 5  # Change from 3 to 5

Adjust Autoscaling:

# k8s/hpa.yaml
spec:
  minReplicas: 5  # Scale up baseline
  maxReplicas: 20  # Allow more pods

Add Environment Variables:

# k8s/configmap.yaml
data:
  CUSTOM_VAR: "value"

🎓 Learning Resources

🏆 Best Practices Implemented

✅ Multi-stage Docker builds (smaller images)
✅ Non-root containers (security)
✅ Health checks (reliability)
✅ Resource limits (stability)
✅ Horizontal autoscaling (performance)
✅ Zero-downtime deployments (availability)
✅ Comprehensive E2E tests (quality)
✅ Privacy-first design (compliance)
✅ Bilingual support (accessibility)
✅ SDG alignment (social impact)

🎉 Ready to Deploy!

Next Steps:

  1. Run .\deploy.ps1 and choose your deployment option
  2. Access the application
  3. Run Cypress tests to validate everything works
  4. Review DEPLOYMENT.md for advanced configurations

Built with ❤️ for LGBTQ+ community | SDG 3, 5, 10 Aligned