Update branding assets and deployment configurations

- Enhanced moebius ring logo design in Blender - Updated Docker Compose for website-only deployment with improved config - Enhanced teaser layout with updated branding integration - Added installation and setup documentation - Consolidated planning and reports documentation - Updated gitignore to exclude Next.js build artifacts and archives 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-27 07:45:08 +10:00
parent 8162496c11
commit 4ed167e734
38 changed files with 13841 additions and 6 deletions
--- a/reports/DOCKER.md
+++ b/reports/DOCKER.md
@@ -0,0 +1,361 @@
+# 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`