reverse-proxy/DEPLOYMENT.md

🚀 Deployment Guide

This guide covers different deployment options for the NGINX Proxy Manager Backend.

🐳 Docker Deployment (Recommended)

Prerequisites

• Docker and Docker Compose installed
• Ports 80, 443, and optionally 3000 available
• Domain(s) pointing to your server

Quick Start

1. Clone and Configure

   git clone <repository-url>
   cd reverse-proxy
   cp .env.example .env
   # Edit .env with your configuration
   

2. Update Docker Compose Edit docker-compose.yml and change:

   • JWT_SECRET to a secure random string
   • ADMIN_PASSWORD to a secure password
   • CORS_ORIGIN to your frontend domain

3. Deploy

   docker-compose up -d
   

4. Check Status

   docker-compose ps
   docker-compose logs -f nginx-proxy-manager
   

5. Access API

   • Health check: http://your-server:3000/api/health
   • Login: POST http://your-server:3000/api/auth/login

Production Configuration

For production, edit docker-compose.yml:

# Remove API port exposure for security
ports:
  - "80:80"
  - "443:443"
  # - "3000:3000"  # Remove this line

# Use environment file
env_file:
  - .env.production

# Add resource limits
deploy:
  resources:
    limits:
      memory: 512M
      cpus: '0.5'

🖥️ Native Installation

Prerequisites

• Ubuntu 20.04+ or similar Linux distribution
• Node.js with Bun runtime
• NGINX installed and running
• acme.sh or certbot for SSL certificates

Installation Steps

1. Install Dependencies

   # Install Bun
   curl -fsSL https://bun.sh/install | bash
   
   # Install NGINX
   sudo apt update
   sudo apt install nginx
   
   # Install acme.sh
   curl https://get.acme.sh | sh -s email=your-email@domain.com
   

2. Setup Application

   git clone <repository-url>
   cd reverse-proxy
   bun install
   cp .env.example .env
   # Edit .env with your configuration
   

3. Initialize Database

   bun run db:init
   

4. Create Systemd Service

   sudo tee /etc/systemd/system/nginx-proxy-manager.service > /dev/null <<EOF
   [Unit]
   Description=NGINX Proxy Manager API
   After=network.target
   
   [Service]
   Type=simple
   User=root
   WorkingDirectory=/path/to/reverse-proxy
   ExecStart=/root/.bun/bin/bun index.ts
   Restart=always
   RestartSec=5
   Environment=NODE_ENV=production
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

5. Start Service

   sudo systemctl daemon-reload
   sudo systemctl enable nginx-proxy-manager
   sudo systemctl start nginx-proxy-manager
   

🔒 Security Hardening

1. Firewall Configuration

# Allow only necessary ports
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

2. SSL/TLS Configuration

• Use strong SSL ciphers (already configured)
• Enable HTTP/2 (configured in NGINX)
• Use HSTS headers for enhanced security

3. Rate Limiting

• API requests: 10 req/sec (configured)
• Login attempts: 1 req/sec (configured)
• Customize in docker/nginx.conf if needed

4. Access Control

• Change default admin credentials immediately
• Use strong JWT secrets
• Consider IP whitelisting for admin access

📊 Monitoring and Maintenance

1. Log Monitoring

# Application logs
docker-compose logs -f nginx-proxy-manager

# NGINX logs
docker-compose exec nginx-proxy-manager tail -f /var/log/nginx/access.log
docker-compose exec nginx-proxy-manager tail -f /var/log/nginx/error.log

2. Health Checks

# API health
curl http://localhost:3000/api/health

# NGINX status
curl -I http://your-domain.com

3. Database Backup

# Manual backup
docker-compose exec nginx-proxy-manager cp /app/data/proxy_manager.db /app/backups/

# Automated backup is included in docker-compose.yml

4. Certificate Monitoring

• Certificates are automatically renewed 30 days before expiry
• Check certificate status via API: /api/certificates/expiring/check
• Force renewal: /api/certificates/expiring/renew

🔄 Updates and Maintenance

1. Update Application

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose build --no-cache
docker-compose up -d

2. Database Migration

# Backup database before updates
docker-compose exec nginx-proxy-manager cp /app/data/proxy_manager.db /app/backups/backup-$(date +%Y%m%d).db

# Run initialization (handles schema updates)
docker-compose exec nginx-proxy-manager bun src/database/init.ts

🐛 Troubleshooting

Common Issues

1. Port Already in Use

   # Check what's using the port
   sudo netstat -tulpn | grep :80
   sudo netstat -tulpn | grep :443
   
   # Stop conflicting services
   sudo systemctl stop apache2  # if Apache is running
   

2. Permission Denied for NGINX Config

   # Fix permissions
   sudo chown -R root:root /etc/nginx/conf.d/
   sudo chmod 644 /etc/nginx/conf.d/*.conf
   

3. SSL Certificate Issues

   # Check acme.sh logs
   docker-compose exec nginx-proxy-manager cat /root/.acme.sh/acme.sh.log
   
   # Manual certificate request
   docker-compose exec nginx-proxy-manager /root/.acme.sh/acme.sh --issue -d yourdomain.com --standalone
   

4. Database Locked

   # Stop application
   docker-compose stop nginx-proxy-manager
   
   # Remove lock file
   docker-compose exec nginx-proxy-manager rm -f /app/data/proxy_manager.db-wal /app/data/proxy_manager.db-shm
   
   # Restart
   docker-compose start nginx-proxy-manager
   

Log Analysis

# Search for errors
docker-compose logs nginx-proxy-manager | grep -i error

# Monitor in real-time
docker-compose logs -f --tail=100 nginx-proxy-manager

📞 Support

1. Check application logs first
2. Verify NGINX configuration with nginx -t
3. Test API endpoints manually
4. Check certificate expiry dates
5. Review firewall and DNS settings

For persistent issues, create a detailed bug report with:

• Error messages and logs
• Configuration details
• Steps to reproduce
• Environment information