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

# 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

# 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

# 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

# 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

# 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

# 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