git/metabuilder

Fork 0

mirror of https://github.com/johndoe6345789/metabuilder.git synced 2026-04-26 14:54:55 +00:00

Files

johndoe6345789 862cc29457 various changes

2026-03-09 22:30:41 +00:00

12 KiB

Raw Permalink Blame History

Phase 8 Nginx Reverse Proxy - File Index

Status: ✅ COMPLETE Created: 2026-01-24 Total Files: 9 Total Lines: 2,800+

Getting Started

First Time? → Read QUICKSTART.md (5 min)
Development Setup → Run ./generate-dev-certs.sh (2 min)
Docker Compose → Merge docker-compose-snippet.yml
Full Details → See README.md (30 min)

SSL & Certificates

Development Certs → Use generate-dev-certs.sh (automated)
Production Certs → See SSL_SETUP.md - Let's Encrypt section
Certificate Issues → See SSL_SETUP.md - Troubleshooting section

Configuration

Nginx Settings → Edit nginx.conf (documented inline)
Docker Build → See Dockerfile
Docker Ignore → See .dockerignore

Documentation

Complete Guide → README.md (600+ lines)
SSL Setup → SSL_SETUP.md (650+ lines)
Quick Start → QUICKSTART.md (200+ lines)
Phase Summary → ../PHASE_8_NGINX_REVERSE_PROXY.md (600+ lines)

File Descriptions

📦 Production Code

`Dockerfile` (40 lines)

Alpine 1.27 Nginx image with health checks and DH parameters.

Key Points:

Lightweight (15MB)
Health check on HTTP
DH parameters generation
Curl for monitoring

Build:

docker build -t metabuilder-email-nginx:latest .

`nginx.conf` (492 lines)

Complete production-ready Nginx configuration with:

HTTP/HTTPS routing
Rate limiting (100 req/min per IP)
Gzip compression
Smart caching
Security headers
SSL/TLS configuration

Key Sections:

Lines 1-80:     Global configuration (workers, logging)
Lines 81-150:   HTTP core (MIME types, buffering, gzip)
Lines 151-200:  Upstream servers
Lines 201-250:  Rate limiting zones
Lines 251-310:  Cache paths
Lines 311-370:  HTTP redirect server (port 80)
Lines 371-540:  Email Service HTTPS server (port 443)
Lines 541-750:  EmailClient HTTPS server (port 443)
Lines 751-800:  Fallback server

Important Lines:

Line 9: worker_processes auto; - Auto-scale to CPU count
Line 50: gzip on; - Enable compression
Line 55: gzip_comp_level 6; - Compression level
Line 78: rate=100r/m; - Rate limit (100 req/min)
Line 85: proxy_cache_path ... api_cache - API cache
Line 92: proxy_cache_path ... static_cache - Static cache

Editing Tips:

Search for ssl_certificate to update cert paths
Search for server_name to update domains
Search for upstream email_service to change backend host
Search for limit_req_zone to adjust rate limits

`.dockerignore` (54 lines)

Optimizes Docker image build by excluding unnecessary files.

🔧 Automation & Integration

`generate-dev-certs.sh` (113 lines)

Interactive script to generate self-signed SSL certificates.

Creates:

ssl/cert.pem - SSL certificate
ssl/key.pem - Private key
ssl/dhparam.pem - DH parameters

Features:

Color-coded output
Verifies key/cert match
Shows certificate details
Sets correct permissions

Usage:

./generate-dev-certs.sh
# Generates certificates in ssl/ directory

Output:

Certificate expires: Jan 24 12:34:56 2027 GMT
SSL certificates generated successfully!

`docker-compose-snippet.yml` (238 lines)

Docker Compose template for integrating Nginx with email services.

Includes:

Nginx service (port 80/443)
Email-service integration
EmailClient integration
Volume definitions
Health checks
Resource limits
Usage notes

Integration Steps:

Copy content from snippet
Merge into main docker-compose.yml
Update service names if different
Run docker-compose up -d

Key Services:

services:
  nginx:          # Reverse proxy
  email-service:  # Python Flask backend
  emailclient:    # Next.js frontend

📚 Documentation

`README.md` (498 lines)

Comprehensive guide covering all features and operations.

Contents:

Overview & Architecture (30 lines)
Prerequisites & Build (50 lines)
Docker Compose Integration (60 lines)
Configuration Breakdown (150 lines)
- HTTP redirect
- Email Service API
- EmailClient frontend
- Rate limiting details
SSL/TLS (40 lines)
Gzip Compression (30 lines)
Health Checks (20 lines)
Performance Tuning (50 lines)
Troubleshooting (80 lines)
Production Checklist (30 lines)
Benchmarks (20 lines)

Quick Sections:

## Rate Limiting - How limits work
## Caching Strategy - Cache configuration
## SSL/TLS Configuration - Security headers
## Troubleshooting - Common issues & solutions

Read When:

Setting up for first time
Configuring rate limits
Troubleshooting issues
Deploying to production

`SSL_SETUP.md` (583 lines)

Complete SSL certificate generation and management guide.

Sections:

Development (150 lines)
- Self-signed certificate generation
- Manual setup with OpenSSL
- Certificate verification
- Browser trust setup
Production (200 lines)
- Let's Encrypt with Certbot
- Docker-based setup
- Manual Certbot installation
- Certificate copying
Renewal (100 lines)
- Automatic renewal hooks
- Systemd timer config
- Docker renewal
- Expiration monitoring
Troubleshooting (80 lines)
- Certificate issues
- ACME challenge failures
- Renewal problems
- Weak DH parameters
Security (50 lines)
- Certificate security
- Strong DH params
- HSTS headers
- Backup procedures

Read When:

First time generating certs
Renewing certificates
Troubleshooting SSL issues
Setting up production

`QUICKSTART.md` (199 lines)

Quick reference guide with commands and examples.

Sections:

30-Second Setup (15 lines)
- Generate certs
- Build image
- Run container
- Verify health
5-Minute Setup (15 lines)
- Generate certs
- Merge compose file
- Start services
- Verify health
Common Commands (60 lines)
- Testing
- Monitoring
- Troubleshooting
- Production
File Structure (10 lines)
Configuration Overview (20 lines)
Production Checklist (15 lines)
Next Steps (20 lines)

Use For:

Quick reference while working
Common commands copy/paste
Pre-flight checks
Production deployment

`PHASE_8_NGINX_REVERSE_PROXY.md` (583 lines)

Comprehensive phase summary document.

Location: /Users/rmac/Documents/metabuilder/emailclient/PHASE_8_NGINX_REVERSE_PROXY.md

Contents:

Overview (20 lines)
Architecture diagram
File descriptions
Key features (10+ subsections)
Technical specifications
Performance characteristics
Integration with other phases
Development workflow
Production deployment
Testing guide
Security considerations
Monitoring & alerting
Maintenance schedule
Known issues
Future enhancements

Read When:

Understanding the full implementation
Planning integration
Deciding architecture changes
Understanding performance targets

Configuration Quick Reference

SSL Certificate Paths

ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
ssl_dhparam /etc/nginx/ssl/dhparam.pem;

Rate Limiting

limit_req_zone $binary_remote_addr zone=email_service_limit:10m rate=100r/m;
# 100 requests per minute per IP
# Burst: 10 requests allowed
# Zone name: email_service_limit

Upstream Servers

upstream email_service {
  least_conn;  # Load balancing
  server email-service:5000;
}

upstream emailclient_nextjs {
  least_conn;
  server emailclient:3000;
}

Cache Configuration

proxy_cache_path /var/cache/nginx/api_cache
  levels=1:2
  keys_zone=api_cache:10m
  max_size=100m
  inactive=60m;

Caching Rules

Static assets (/_next/):  24 hours
HTML pages (/):           1 minute
API responses (/api/):    5 minutes

Security Headers

add_header Strict-Transport-Security "max-age=31536000";
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Content-Security-Policy "default-src 'self'";

Development Workflow

Day 1: Setup

cd emailclient/deployment/docker/nginx

# 1. Generate certificates
./generate-dev-certs.sh

# 2. Build image
docker build -t metabuilder-email-nginx:latest .

# 3. Run container
docker run -d -p 80:80 -p 443:443 \
  -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
  -v $(pwd)/ssl:/etc/nginx/ssl:ro \
  metabuilder-email-nginx:latest

# 4. Verify
curl -k https://localhost/health

Daily: Testing

# Health check
curl -k https://localhost/health

# View logs
docker logs -f emailclient-nginx

# Test rate limiting
for i in {1..105}; do curl -s https://api.emailclient.local/ > /dev/null & done

Before Production

# 1. Generate Let's Encrypt cert (see SSL_SETUP.md)
# 2. Update nginx.conf domains
# 3. Update docker-compose.yml
# 4. Test full stack
# 5. Deploy

File Organization

emailclient/
├── deployment/
│   └── docker/
│       └── nginx/
│           ├── Dockerfile              (40 lines)
│           ├── nginx.conf              (492 lines)
│           ├── README.md               (498 lines)
│           ├── SSL_SETUP.md            (583 lines)
│           ├── QUICKSTART.md           (199 lines)
│           ├── INDEX.md                (this file)
│           ├── generate-dev-certs.sh   (113 lines)
│           ├── docker-compose-snippet.yml (238 lines)
│           ├── .dockerignore           (54 lines)
│           └── ssl/                    (generated)
│               ├── cert.pem
│               ├── key.pem
│               └── dhparam.pem
├── PHASE_8_NGINX_REVERSE_PROXY.md      (583 lines)
└── ...other phase files...

Command Reference

Certificate Generation

./generate-dev-certs.sh          # Interactive script
openssl req -new -x509 ...       # Manual certificate
openssl x509 -enddate -noout ... # Check expiration

Docker Commands

docker build -t metabuilder-email-nginx:latest .
docker run -d -p 80:80 -p 443:443 ...
docker logs emailclient-nginx
docker exec emailclient-nginx nginx -t
docker exec emailclient-nginx nginx -s reload

Testing

curl -k https://localhost/health              # Health check
curl -i http://localhost                      # HTTP redirect
docker exec ... curl http://email-service:5000  # Upstream test

Monitoring

docker logs -f emailclient-nginx              # Follow logs
docker exec ... tail -f /var/log/nginx/access.log
docker exec ... grep "X-Cache-Status" /var/log/nginx/access.log
docker exec ... grep "limiting requests" /var/log/nginx/access.log

Troubleshooting Guide

Certificate Issues

Problem: SSL certificate warning in browser Solution: See SSL_SETUP.md - "Trust Self-Signed Certificates"

Rate Limiting

Problem: Getting 429 errors Solution: Check README.md - "Rate Limiting" section

Upstream Connection

Problem: 502 Bad Gateway Solution: See README.md - "Troubleshooting" section

High Memory/CPU

Problem: Container using too much resources Solution: See README.md - "Performance Tuning"

Version History

Version	Date	Changes
1.0.0	2026-01-24	Initial release - Phase 8 complete

Next Files in Series

Support Resources

Need	Location
Quick setup	QUICKSTART.md
Full guide	README.md
SSL help	SSL_SETUP.md
Configuration	nginx.conf (inline comments)
Phase overview	PHASE_8_NGINX_REVERSE_PROXY.md
Implementation plan	../../docs/plans/2026-01-23-email-client-implementation.md

Total Lines Across All Files: 2,800+ Status: Production Ready Last Updated: 2026-01-24

12 KiB Raw Permalink Blame History

Phase 8 Nginx Reverse Proxy - File Index

Quick Navigation

Getting Started

SSL & Certificates

Configuration

Documentation

File Descriptions

📦 Production Code

Dockerfile (40 lines)

nginx.conf (492 lines)

.dockerignore (54 lines)

🔧 Automation & Integration

generate-dev-certs.sh (113 lines)

docker-compose-snippet.yml (238 lines)

📚 Documentation

README.md (498 lines)

SSL_SETUP.md (583 lines)

QUICKSTART.md (199 lines)

PHASE_8_NGINX_REVERSE_PROXY.md (583 lines)

Configuration Quick Reference

SSL Certificate Paths

Rate Limiting

Upstream Servers

Cache Configuration

Caching Rules

Security Headers

Development Workflow

Day 1: Setup

Daily: Testing

Before Production

File Organization

Command Reference

Certificate Generation

Docker Commands

Testing

Monitoring

Troubleshooting Guide

Certificate Issues

Rate Limiting

Upstream Connection

High Memory/CPU

Version History

Next Files in Series

Support Resources

12 KiB

Raw Permalink Blame History

`Dockerfile` (40 lines)

`nginx.conf` (492 lines)

`.dockerignore` (54 lines)

`generate-dev-certs.sh` (113 lines)

`docker-compose-snippet.yml` (238 lines)

`README.md` (498 lines)

`SSL_SETUP.md` (583 lines)

`QUICKSTART.md` (199 lines)

`PHASE_8_NGINX_REVERSE_PROXY.md` (583 lines)