cal/claude-home
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
50125d8b39
claude-home/networking/npm-configuration.md
Cal Corum 4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Details
docs: add YAML frontmatter to all 151 markdown files 
Adds title, description, type, domain, and tags frontmatter to every
doc for improved KB semantic search. The description field is prepended
to every search chunk, and domain/type/tags enable filtered queries.

Type values: context, guide, runbook, reference, troubleshooting
Domain values match directory structure (networking, docker, etc.)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 09:00:44 -05:00

357 lines
11 KiB
Markdown
Raw Blame History

---
title: "Nginx Proxy Manager Configuration"
description: "Complete NPM reverse proxy configuration for manticorum.com services including proxy hosts, SSL certificates, advanced routing, CORS, and operational procedures."
type: reference
domain: networking
tags: [nginx-proxy-manager, npm, ssl, letsencrypt, reverse-proxy, manticorum]
---
# 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
Reference in New Issue View Git Blame Copy Permalink