diff --git a/CLAUDE.md b/CLAUDE.md index e71912b..a66f2e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,10 +37,11 @@ When working with specific technologies, automatically load their dedicated cont - If working in `/vm-management/scripts/`: Load `vm-management/scripts/CONTEXT.md` (script-specific documentation) **Networking Keywords** -- "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall", "ssh", "ssl", "tls" +- "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall", "ssh", "ssl", "tls", "npm", "nginx proxy manager", "reverse proxy" - Load: `networking/CONTEXT.md` (technology overview and patterns) - Load: `networking/troubleshooting.md` (error handling and debugging) - If working in `/networking/scripts/`: Load `networking/scripts/CONTEXT.md` (script-specific documentation) + - Note: Comprehensive NPM configuration documented in `networking/npm-configuration.md` **Monitoring Keywords** - "monitoring", "alert", "notification", "discord", "health check", "status", "uptime", "windows reboot", "system monitor" diff --git a/networking/npm-configuration.md b/networking/npm-configuration.md new file mode 100644 index 0000000..d54e5e9 --- /dev/null +++ b/networking/npm-configuration.md @@ -0,0 +1,349 @@ +# Nginx Proxy Manager Configuration Documentation + +## Overview +Nginx Proxy Manager (NPM) serves as the primary reverse proxy for manticorum.com services, running on 10.10.0.16:82 alongside Pi-hole DNS service. This document provides comprehensive details of the current configuration for operational reference and troubleshooting. + +## Infrastructure Details + +### NPM Server Information +- **Host**: 10.10.0.16 (pihole/dns server) +- **Management Interface**: http://10.10.0.16:82 +- **Container**: `nginx-proxy-manager_app_1` +- **Data Directory**: `/data` (contains database.sqlite, SSL certificates, logs) +- **Port Mapping**: + - 80:80 (HTTP) + - 443:443 (HTTPS) + - 82:81 (Management UI) + +### Domain Strategy +- **Primary Domain**: manticorum.com +- **SSL Provider**: Let's Encrypt (automatic renewal) +- **DNS Resolution**: Internal DNS at 10.10.0.16 (Pi-hole) + +## Current Proxy Host Configurations + +### Production Services (SSL Enabled) + +#### SBA Main Application +- **Domain**: `sba.manticorum.com` +- **Primary Target**: 10.10.0.88:803 +- **SSL**: Enabled (Force HTTPS) +- **Certificate**: Let's Encrypt (expires 2025-09-24) +- **Advanced Routing**: + - `/api/*` → 10.10.0.42:801 (with CORS headers) + - `/cards/*` → 10.10.0.42:804 +- **Status**: Active + +#### SBA News/Blog +- **Domain**: `sbanews.manticorum.com` +- **Target**: 10.10.0.88:2368 +- **SSL**: Enabled (Force HTTPS) +- **Certificate**: Let's Encrypt (expires 2025-10-14) +- **Application**: Ghost blog platform +- **Status**: Active + +#### PD Main Application +- **Domain**: `pd.manticorum.com` +- **Target**: 10.10.0.42:815 +- **SSL**: Enabled (Force HTTPS) +- **Certificate**: Let's Encrypt (expires 2025-10-14) +- **Status**: Active + +#### FoundryVTT +- **Domain**: `foundry.manticorum.com` +- **Target**: 10.10.0.33:30000 +- **SSL**: Enabled (Force HTTPS) +- **Certificate**: Let's Encrypt (expires 2025-10-14) +- **Application**: Virtual tabletop gaming platform +- **Status**: Active + +#### Pokemon Strategy App +- **Domain**: `pokestrat.manticorum.com` +- **Target**: 10.10.0.33:30000 +- **SSL**: Enabled (Force HTTPS) +- **Certificate**: Let's Encrypt (expires 2025-10-14) +- **Status**: Active + +### Development Services (HTTP) + +#### SBA Development +- **Domain**: `sbadev.manticorum.com` +- **Primary Target**: 10.10.0.33:802 +- **SSL**: Disabled +- **Certificate**: Let's Encrypt available (expires 2025-10-14) +- **Advanced Routing**: + - `/api/*` → 10.10.0.42:814 (with CORS headers) +- **Status**: Active + +#### PD Development +- **Domain**: `pddev.manticorum.com` +- **Primary Target**: 10.10.0.42:813 +- **SSL**: Disabled +- **Certificate**: Let's Encrypt available (expires 2025-10-14) +- **Advanced Routing**: + - `/api/*` → 10.10.0.42:813 (same backend) +- **Status**: Active + +### Media Services + +#### Plex Media Server +- **Domain**: `plex.manticorum.com` +- **Target**: 10.10.0.20:32400 +- **SSL**: Disabled +- **Certificate**: None configured +- **Status**: Active +- **Note**: Plex handles its own HTTPS internally + +### Disabled Services + +#### Project Sol +- **Domain**: `projectsol.manticorum.com` +- **Target**: 10.0.0.252:30000 (different subnet) +- **SSL**: Disabled +- **Status**: **DISABLED** +- **Note**: Service appears to be decommissioned + +## SSL Certificate Management + +### Active Certificates (Let's Encrypt) +| Domain | Expires | Status | Auto-Renewal | +|--------|---------|--------|--------------| +| sba.manticorum.com | 2025-09-24 | ✅ Valid | Yes | +| sbadev.manticorum.com | 2025-10-14 | ✅ Valid | Yes | +| sbanews.manticorum.com | 2025-10-14 | ✅ Valid | Yes | +| pd.manticorum.com | 2025-10-14 | ✅ Valid | Yes | +| pddev.manticorum.com | 2025-10-14 | ✅ Valid | Yes | +| pokestrat.manticorum.com | 2025-10-14 | ✅ Valid | Yes | +| foundry.manticorum.com | 2025-10-14 | ✅ Valid | Yes | + +### Expired Certificates +| Domain | Expired | Action Required | +|--------|---------|-----------------| +| *.manticorum.com | 2023-08-09 | ⚠️ Replace with individual certs or renew wildcard | + +### Certificate Storage +- **Location**: `/data/letsencrypt-acme-challenge/` (container path) +- **Custom SSL**: `/data/custom_ssl/` (for manual certificates) +- **Renewal**: Automatic via Let's Encrypt integration + +## Advanced Routing Configurations + +### Microservices Architecture Pattern + +#### SBA Service Routing +``` +sba.manticorum.com/ +├── /* (default) → 10.10.0.88:803 (frontend) +├── /api/* → 10.10.0.42:801 (API backend + CORS) +└── /cards/* → 10.10.0.42:804 (cards service) +``` + +#### SBA Development Routing +``` +sbadev.manticorum.com/ +├── /* (default) → 10.10.0.33:802 (dev frontend) +└── /api/* → 10.10.0.42:814 (dev API + CORS) +``` + +#### PD Development Routing +``` +pddev.manticorum.com/ +├── /* (default) → 10.10.0.42:813 (app) +└── /api/* → 10.10.0.42:813 (same backend) +``` + +### CORS Configuration +- **Header**: `add_header 'Access-Control-Allow-Origin' *;` +- **Applied to**: API endpoints requiring cross-origin access +- **Services**: SBA API routes, SBA Dev API routes + +## Server Architecture Map + +### Backend Server Roles + +#### 10.10.0.20 - Media Services +- **Service**: Plex Media Server +- **Port**: 32400 +- **SSL**: Self-managed +- **Purpose**: Media streaming and management + +#### 10.10.0.33 - Development Services +- **Services**: + - SBA Development Frontend (port 802) + - FoundryVTT (port 30000) + - Pokemon Strategy App (port 30000) +- **Environment**: Development/Gaming +- **SSL**: Mixed (gaming apps use SSL, dev uses HTTP) + +#### 10.10.0.42 - Database/API Services +- **Services**: + - SBA API (port 801) + - Cards Service (port 804) + - PD Main (port 815) + - PD Dev (port 813) + - SBA Dev API (port 814) +- **Purpose**: Backend APIs and database connections +- **SSL**: Handled by reverse proxy + +#### 10.10.0.88 - Production Services +- **Services**: + - SBA Production Frontend (port 803) + - Ghost Blog/News (port 2368) +- **Environment**: Production +- **SSL**: Force HTTPS enabled + +## Operational Procedures + +### Database Access +```bash +# SSH to NPM server +ssh pihole + +# Copy database for analysis +docker cp nginx-proxy-manager_app_1:/data/database.sqlite /tmp/npm_db.sqlite + +# Query proxy hosts +sqlite3 /tmp/npm_db.sqlite "SELECT domain_names, forward_host, forward_port, ssl_forced, enabled FROM proxy_host WHERE is_deleted = 0;" + +# Query certificates +sqlite3 /tmp/npm_db.sqlite "SELECT nice_name, provider, expires_on FROM certificate WHERE is_deleted = 0;" +``` + +### Container Management +```bash +# Check container status +ssh pihole "docker ps | grep nginx-proxy-manager" + +# View logs +ssh pihole "docker logs nginx-proxy-manager_app_1" + +# Restart container +ssh pihole "docker restart nginx-proxy-manager_app_1" + +# Access container shell +ssh pihole "docker exec -it nginx-proxy-manager_app_1 /bin/bash" +``` + +### Configuration Backup +```bash +# Backup NPM data directory +ssh pihole "docker cp nginx-proxy-manager_app_1:/data /backup/npm-data-$(date +%Y%m%d)" + +# Backup specific database +ssh pihole "docker cp nginx-proxy-manager_app_1:/data/database.sqlite /backup/npm-db-$(date +%Y%m%d).sqlite" +``` + +## Monitoring and Health Checks + +### Service Availability +```bash +# Check proxy host availability +HOSTS="sba.manticorum.com sbanews.manticorum.com pd.manticorum.com foundry.manticorum.com" +for host in $HOSTS; do + if curl -sSf --max-time 10 "https://$host" >/dev/null 2>&1; then + echo "✅ $host: Available" + else + echo "❌ $host: Unavailable" + fi +done +``` + +### SSL Certificate Status +```bash +# Check certificate expiration +echo | openssl s_client -servername sba.manticorum.com -connect sba.manticorum.com:443 2>/dev/null | openssl x509 -noout -dates +``` + +### Container Health +```bash +# Check NPM container health +ssh pihole "docker exec nginx-proxy-manager_app_1 curl -f http://localhost:81/api/schema || echo 'API unhealthy'" +``` + +## Security Configuration + +### Access Control +- **Management Interface**: Limited to internal network (10.10.0.x) +- **SSH Access**: Key-based authentication only +- **Container Isolation**: Docker network isolation +- **Firewall**: Host-based firewall rules (ufw) + +### SSL/TLS Configuration +- **Protocols**: TLS 1.2, TLS 1.3 +- **Cipher Suites**: Modern cipher preferences +- **HSTS**: Enabled for SSL-forced hosts +- **Certificate Validation**: Automated Let's Encrypt validation + +### Security Headers +- **X-Frame-Options**: Applied via NPM +- **X-Content-Type-Options**: Applied via NPM +- **X-XSS-Protection**: Applied via NPM +- **Strict-Transport-Security**: Applied to HTTPS hosts + +## Troubleshooting Guide + +### Common Issues + +#### Certificate Renewal Failures +1. Check Let's Encrypt rate limits +2. Verify DNS resolution for domain +3. Ensure port 80 accessible for HTTP challenges +4. Check NPM logs for specific errors + +#### Service Unavailable +1. Verify target service is running on backend server +2. Check NPM proxy host configuration +3. Test direct connection to backend service +4. Review NPM error logs + +#### Database Corruption +1. Stop NPM container +2. Restore database from backup +3. Restart container and verify configuration + +### Log Locations +- **NPM Logs**: `/data/logs/` (container path) +- **Nginx Access Logs**: `/data/logs/proxy-host-*_access.log` +- **Nginx Error Logs**: `/data/logs/proxy-host-*_error.log` +- **Manager Logs**: `/data/logs/manager.log` + +## Maintenance Schedule + +### Weekly Tasks +- Review SSL certificate expiration dates +- Check service availability for all proxy hosts +- Monitor NPM container resource usage + +### Monthly Tasks +- Backup NPM configuration database +- Review and clean up unused proxy hosts +- Update NPM container image if available +- Audit access logs for security issues + +### Quarterly Tasks +- Review and optimize routing configurations +- Evaluate SSL certificate strategy (wildcard vs individual) +- Performance testing of proxy response times +- Documentation updates based on configuration changes + +## Future Considerations + +### Potential Improvements +1. **Wildcard Certificate**: Renew or replace expired *.manticorum.com certificate +2. **SSL Adoption**: Enable SSL for remaining HTTP services (plex, dev environments) +3. **Load Balancing**: Implement backend redundancy for critical services +4. **Monitoring**: Integrate with monitoring system for automated health checks +5. **Access Lists**: Implement IP-based access control for sensitive services + +### Scalability Notes +- Current architecture supports microservices pattern well +- Database server (10.10.0.42) could benefit from load balancing +- Consider container orchestration (Docker Compose/Swarm) for complex services +- API gateway pattern already partially implemented with location-based routing + +--- + +**Documentation Version**: 1.0 +**Last Updated**: August 19, 2025 +**Maintained By**: Claude Code Assistant +**Configuration Snapshot Date**: August 19, 2025 \ No newline at end of file