reverse-proxy/README.md

# 🔄 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**
   ```bash
   git clone <repository-url>
   cd reverse-proxy
   bun install
   ```

2. **Configure Environment**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

3. **Initialize Database**
   ```bash
   bun run db:init
   ```

4. **Start Development Server**
   ```bash
   bun run dev
   ```

5. **Start Production Server**
   ```bash
   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
```http
POST /api/auth/login
Content-Type: application/json

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

#### Get Current User
```http
GET /api/auth/me
Authorization: Bearer <token>
```

### Proxy Management

#### Get All Proxies
```http
GET /api/proxies
Authorization: Bearer <token>
```

#### Create Proxy
```http
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
```http
PUT /api/proxies/:id
Authorization: Bearer <token>
Content-Type: application/json

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

#### Delete Proxy
```http
DELETE /api/proxies/:id
Authorization: Bearer <token>
```

### Certificate Management

#### Request Let's Encrypt Certificate
```http
POST /api/certificates/letsencrypt
Authorization: Bearer <token>
Content-Type: application/json

{
  "domain": "example.com"
}
```

#### Upload Custom Certificate
```http
POST /api/certificates/custom
Authorization: Bearer <token>
Content-Type: multipart/form-data

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

#### Get Expiring Certificates
```http
GET /api/certificates/expiring/check?days=30
Authorization: Bearer <token>
```

### NGINX Management

#### Test NGINX Configuration
```http
POST /api/proxies/nginx/test
Authorization: Bearer <token>
```

#### Reload NGINX
```http
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.