🔄 Custom NGINX Proxy Manager Backend

A modern, lightweight backend for managing NGINX reverse proxies with automatic SSL certificate management.

🧱 Tech Stack

• Node.js with Bun runtime
• Express.js for API routing
• SQLite for data storage
• NGINX for reverse proxying
• Let's Encrypt (via acme.sh/certbot) for automatic TLS certificates
• JWT for authentication
• TypeScript for type safety

🚀 Features

🔧 Proxy Management

• ✅ Create, read, update, delete reverse proxy entries
• ✅ Domain to target URL mapping
• ✅ HTTP/HTTPS support with automatic redirects
• ✅ Custom headers configuration
• ✅ Path-based forwarding
• ✅ WebSocket support
• ✅ Configurable client max body size

🔒 SSL Certificate Management

• ✅ Automatic Let's Encrypt certificate issuance
• ✅ Custom certificate upload support
• ✅ Automatic certificate renewal
• ✅ Certificate expiry monitoring
• ✅ Certificate validation

🔐 Security

• ✅ JWT-based authentication
• ✅ Password hashing with bcrypt
• ✅ CORS protection
• ✅ Helmet security headers
• ✅ Request validation with Joi

🗄️ Database

• ✅ SQLite database with proper schema
• ✅ Models for users, proxies, and certificates
• ✅ Automatic database initialization

🔁 NGINX Integration

• ✅ Dynamic configuration generation
• ✅ Configuration testing before reload
• ✅ Automatic NGINX reload
• ✅ Error handling and rollback

📁 Project Structure

reverse-proxy/
├── src/
│   ├── config/           # Configuration management
│   ├── controllers/      # Request handlers
│   ├── database/         # Database setup and initialization
│   ├── middleware/       # Express middleware (auth, validation)
│   ├── models/           # Database models
│   ├── routes/           # API routes
│   ├── services/         # Business logic
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Utility functions
├── logs/                 # Application logs
├── nginx/                # NGINX configurations
├── certs/                # Custom SSL certificates
├── data/                 # SQLite database
└── index.ts              # Application entry point

🛠️ Installation

Prerequisites

• Bun runtime installed
• NGINX installed and running
• acme.sh or certbot for Let's Encrypt certificates
• Proper permissions for NGINX config management

Setup

1. Clone and Install Dependencies

   git clone <repository-url>
   cd reverse-proxy
   bun install
   

2. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration
   

3. Initialize Database

   bun run db:init
   

4. Start Development Server

   bun run dev
   

5. Start Production Server

   bun run start
   

🔧 Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	3000
NODE_ENV	Environment	development
DATABASE_PATH	SQLite database path	./data/proxy_manager.db
JWT_SECRET	JWT signing secret	your-secret-key
JWT_EXPIRES_IN	JWT expiration time	24h
ADMIN_USERNAME	Default admin username	admin
ADMIN_PASSWORD	Default admin password	admin123
NGINX_CONFIG_PATH	NGINX config directory	/etc/nginx/conf.d
NGINX_BINARY_PATH	NGINX binary path	/usr/sbin/nginx
SSL_METHOD	SSL method (acme.sh/certbot)	acme.sh
ACME_SH_PATH	acme.sh installation path	/root/.acme.sh
CERTBOT_PATH	certbot binary path	/usr/bin/certbot
CUSTOM_CERTS_PATH	Custom certificates directory	./certs

📚 API Documentation

Authentication

Login

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Proxy Management

Get All Proxies

GET /api/proxies
Authorization: Bearer <token>

Create Proxy

POST /api/proxies
Authorization: Bearer <token>
Content-Type: application/json

{
  "domain": "example.com",
  "target": "http://localhost:8080",
  "ssl_type": "letsencrypt",
  "options": {
    "redirect_http_to_https": true,
    "custom_headers": {
      "X-Custom-Header": "value"
    },
    "path_forwarding": {
      "/api": "http://api-server:3000"
    },
    "enable_websockets": true,
    "client_max_body_size": "10m"
  }
}

Update Proxy

PUT /api/proxies/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "target": "http://localhost:9000",
  "options": {
    "redirect_http_to_https": false
  }
}

Delete Proxy

DELETE /api/proxies/:id
Authorization: Bearer <token>

Certificate Management

Request Let's Encrypt Certificate

POST /api/certificates/letsencrypt
Authorization: Bearer <token>
Content-Type: application/json

{
  "domain": "example.com"
}

Upload Custom Certificate

POST /api/certificates/custom
Authorization: Bearer <token>
Content-Type: multipart/form-data

{
  "domain": "example.com",
  "certificate": <file>,
  "privateKey": <file>
}

Get Expiring Certificates

GET /api/certificates/expiring/check?days=30
Authorization: Bearer <token>

NGINX Management

Test NGINX Configuration

POST /api/proxies/nginx/test
Authorization: Bearer <token>

Reload NGINX

POST /api/proxies/nginx/reload
Authorization: Bearer <token>

🔄 Automatic Certificate Renewal

The system includes automatic certificate renewal that:

• Runs daily at 2:00 AM UTC
• Checks for certificates expiring within 30 days
• Automatically renews Let's Encrypt certificates
• Logs all renewal activities

🐛 Troubleshooting

Common Issues

1. NGINX reload fails

   • Check NGINX configuration syntax
   • Verify file permissions
   • Check NGINX error logs

2. Certificate request fails

   • Ensure domain points to server
   • Check firewall settings (port 80/443)
   • Verify acme.sh/certbot installation

3. Database errors

   • Check file permissions for database directory
   • Ensure SQLite is available

Logs

Application logs are stored in the logs/ directory:

• app.log - General application logs
• app-error.log - Error logs only

🔒 Security Considerations

1. Change default admin credentials immediately after setup
2. Use strong JWT secrets in production
3. Configure proper file permissions for certificates
4. Enable HTTPS for the API in production
5. Regular security updates for all components

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review application logs
3. Create an issue on GitHub

---

⚠️ Important: This is a powerful tool that manages NGINX configurations and SSL certificates. Always test changes in a development environment first.