claude-home/networking/npm-configuration.md

# 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