chorus-services-website/DOCKER.md

CHORUS Services Website - Docker Configuration

This document provides comprehensive guidance on using the Docker configuration for the CHORUS Services website.

Architecture Overview

The website uses a production-optimized Docker setup designed to integrate seamlessly with the existing CHORUS Services infrastructure:

• Production: Next.js standalone server running on port 80
• Load Balancing: Traefik with Let's Encrypt SSL
• Registry: registry.home.deepblack.cloud/tony/chorus-website:latest
• Network: tengig (external-facing via Traefik)
• Domains: www.chorus.services, chorus.services (redirect)

File Structure

website/
├── Dockerfile              # Production multi-stage build
├── Dockerfile.dev          # Development environment
├── docker-compose.yml      # Local development stack
├── .dockerignore           # Build context optimization
├── nginx.conf              # Nginx configuration (not used in simplified setup)
├── healthcheck.js          # Full health check script
├── healthcheck-simple.js   # Simplified health check for production
└── DOCKER.md              # This documentation

Quick Start

1. Local Development

Start the development environment:

# Basic development server
docker-compose up website-dev

# With additional services (cache, database, email)
docker-compose --profile cache --profile database --profile email up

Access the application:

• Website: http://localhost:3000
• Mailhog (email testing): http://localhost:8025

2. Production Build and Test

Test the production build locally:

# Build and run production container
docker-compose --profile production up website-prod

# Access via:
# - Nginx: http://localhost:8080
# - Next.js direct: http://localhost:8081

3. Build and Push to Registry

From the project root (/home/tony/AI/projects/chorus.services/):

# Build and push website only
./build-and-push.sh website

# Build and push all services
./build-and-push.sh

4. Deploy to Production

# Deploy the entire CHORUS stack
docker stack deploy -c docker-compose.swarm.yml chorus

# Update website only
docker service update chorus_chorus-website --image registry.home.deepblack.cloud/tony/chorus-website:latest --force

Docker Configuration Details

Production Dockerfile

Multi-stage build optimizations:

• Stage 1 (base): Node.js 18 Alpine base
• Stage 2 (deps): Production dependencies only
• Stage 3 (builder): Full build with all dependencies
• Stage 4 (runner): Minimal runtime with Next.js standalone

Security features:

• Non-root user (nextjs:1001)
• Minimal attack surface (Alpine Linux)
• No unnecessary packages in final image
• Proper file permissions

Performance optimizations:

• Multi-stage build reduces final image size
• npm cache optimization
• Layer caching for faster rebuilds
• Standalone Next.js output

Health Checks

The container includes comprehensive health checking:

// Simple health check (production)
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD node /app/healthcheck.js || exit 1

Health check validates:

• Next.js server responding on port 80
• Response time under 5 seconds
• HTTP status codes 200-399

Environment Variables

Production environment:

NODE_ENV=production
NEXT_TELEMETRY_DISABLED=1
PORT=80
HOSTNAME=0.0.0.0

Development environment:

NODE_ENV=development
NEXT_TELEMETRY_DISABLED=1
CHOKIDAR_USEPOLLING=true
WATCHPACK_POLLING=true

Integration with CHORUS Infrastructure

Traefik Configuration

The website service in docker-compose.swarm.yml includes:

labels:
  - "traefik.enable=true"
  - "traefik.docker.network=tengig"
  - "traefik.http.routers.chorus-website.rule=Host(`www.chorus.services`) || Host(`chorus.services`)"
  - "traefik.http.routers.chorus-website.entrypoints=web-secured"
  - "traefik.http.routers.chorus-website.tls.certresolver=letsencryptresolver"
  - "traefik.http.services.chorus-website.loadbalancer.server.port=80"
  - "traefik.http.services.chorus-website.loadbalancer.passhostheader=true"

Domain Redirect

Automatic redirect from naked domain to www:

- "traefik.http.middlewares.chorus-redirect.redirectregex.regex=^https://chorus.services/(.*)"
- "traefik.http.middlewares.chorus-redirect.redirectregex.replacement=https://www.chorus.services/$${1}"
- "traefik.http.routers.chorus-website.middlewares=chorus-redirect"

Resource Limits

Production deployment constraints:

deploy:
  replicas: 2
  resources:
    limits:
      memory: 128M
    reservations:
      memory: 64M

Development Profiles

The docker-compose.yml includes several profiles for different development scenarios:

Basic Development

docker-compose up website-dev

• Next.js development server with hot reloading
• Source code mounted for live editing

With Caching

docker-compose --profile cache up

• Includes Redis for caching development
• Useful for testing cache-dependent features

With Database

docker-compose --profile database up

• PostgreSQL for future features requiring persistence
• Pre-configured with development database

With Email Testing

docker-compose --profile email up

• Mailhog for testing email functionality
• SMTP server on localhost:1025
• Web UI on localhost:8025

SSL Testing

docker-compose --profile ssl up

• Local SSL/TLS testing environment
• Requires SSL certificates in docker/ssl/

Performance Targets

The Docker configuration meets the following performance targets:

• Image Size: <100MB (production)
• Build Time: <5 minutes
• Container Startup: <10 seconds
• Health Check Response: <5 seconds

Security Best Practices

Container Security

• Non-root user execution
• Minimal base image (Alpine Linux)
• No unnecessary packages in production
• Proper file permissions and ownership

Network Security

• No direct port exposure (all traffic via Traefik)
• HTTPS-only external access
• Internal service communication via Docker networks

Secrets Management

• No secrets in Docker images
• Environment variables for configuration
• Registry credentials managed separately

Troubleshooting

Common Issues

Build failures:

# Clear Docker build cache
docker builder prune -a

# Rebuild without cache
docker-compose build --no-cache website-dev

Health check failures:

# Check container logs
docker logs <container-id>

# Test health check manually
docker exec <container-id> node /app/healthcheck.js

Network connectivity:

# Check Traefik labels
docker service inspect chorus_chorus-website

# Verify tengig network
docker network inspect tengig

Performance Monitoring

Monitor container performance:

# Resource usage
docker stats

# Service logs
docker service logs chorus_chorus-website -f

# Health check history
docker service ps chorus_chorus-website

Maintenance

Regular Tasks

Update base images:

# Pull latest Node.js image
docker pull node:18-alpine

# Rebuild containers
./build-and-push.sh website

Security updates:

# Update dependencies
npm audit fix

# Rebuild and redeploy
./build-and-push.sh website
docker service update chorus_chorus-website --force

Certificate renewal:

• Let's Encrypt certificates auto-renew via Traefik
• Monitor certificate expiration via Grafana dashboards

Integration Testing

Test the complete deployment pipeline:

# 1. Build locally
docker build -t test-website .

# 2. Test production image
docker run -p 8080:80 test-website

# 3. Verify health checks
curl -f http://localhost:8080/

# 4. Push to registry
./build-and-push.sh website

# 5. Deploy to production
docker service update chorus_chorus-website --image registry.home.deepblack.cloud/tony/chorus-website:latest --force

Support and Monitoring

The website integrates with the existing CHORUS monitoring stack:

• Metrics: Prometheus scraping via service discovery
• Logs: Centralized logging via Docker Swarm
• Dashboards: Grafana monitoring dashboards
• Alerts: Alert manager for critical issues

For support, check:

1. Service logs: docker service logs chorus_chorus-website
2. Traefik dashboard: https://chorus-traefik.home.deepblack.cloud
3. Grafana dashboards: https://chorus-grafana.home.deepblack.cloud