chorus-services/planning and reports/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:

```bash
# 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:

```bash
# 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/`):

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

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

### 4. Deploy to Production

```bash
# 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:

```javascript
// 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:**
```bash
NODE_ENV=production
NEXT_TELEMETRY_DISABLED=1
PORT=80
HOSTNAME=0.0.0.0
```

**Development environment:**
```bash
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:

```yaml
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:
```yaml
- "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:
```yaml
deploy:
  replicas: 2
  resources:
    limits:
      memory: 128M
    reservations:
      memory: 64M
```

## Brand-Aware Development Profiles

The `docker-compose.yml` includes brand-specific profiles for comprehensive development:

### Basic Brand Development
```bash
docker-compose up website-dev
```
- Next.js development server with CHORUS brand hot reloading
- Tailwind CSS with 8-color system compilation
- Three.js logo development mode
- Accessibility theme switching enabled
- Source code mounted for live editing

### Brand Asset Development
```bash
docker-compose --profile brand-assets up
```
- Advanced Tailwind CSS compilation with brand tokens
- Three.js shader development tools
- Logo material editor for accessibility themes
- Font loading optimization (Inter Tight, Exo, Inconsolata)
- Real-time brand compliance checking

### With Caching
```bash
docker-compose --profile cache up
```
- Includes Redis for caching development
- Useful for testing cache-dependent features

### With Database
```bash
docker-compose --profile database up
```
- PostgreSQL for future features requiring persistence
- Pre-configured with development database

### With Email Testing
```bash
docker-compose --profile email up
```
- Mailhog for testing email functionality
- SMTP server on localhost:1025
- Web UI on localhost:8025

### SSL Testing
```bash
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:**
```bash
# Clear Docker build cache
docker builder prune -a

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

**Health check failures:**
```bash
# Check container logs
docker logs <container-id>

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

**Network connectivity:**
```bash
# Check Traefik labels
docker service inspect chorus_chorus-website

# Verify tengig network
docker network inspect tengig
```

### Performance Monitoring

Monitor container performance:
```bash
# 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:**
```bash
# Pull latest Node.js image
docker pull node:18-alpine

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

**Security updates:**
```bash
# 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:

```bash
# 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`