CLAUDE: Add comprehensive Nginx Proxy Manager configuration documentation
- Document all 9 proxy hosts with SSL status and routing details - Add NPM database access procedures and container management commands - Include microservices routing patterns for SBA and PD applications - Document SSL certificate management and expiration tracking - Add operational procedures, troubleshooting guide, and maintenance schedules - Update CLAUDE.md with NPM-specific keywords for automatic context loading 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
edc78c2dd6
commit
059fbdd906
@ -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"
|
||||
|
||||
349
networking/npm-configuration.md
Normal file
349
networking/npm-configuration.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user