# Nginx Proxy Manager Setup for Atlas CMMS

This guide explains how to configure Nginx Proxy Manager to handle SSL certificates and reverse proxy for the Atlas CMMS application.

## Overview

Nginx Proxy Manager provides:
- **SSL Certificate Management**: Automatic Let's Encrypt certificates
- **Reverse Proxy**: Route traffic to backend services
- **Web Interface**: Easy configuration through GUI
- **Access Control**: IP filtering and basic authentication
- **Custom SSL**: Upload your own certificates

## Initial Setup

### 1. Access Nginx Proxy Manager Admin Interface

After running `docker-compose up`, access the admin interface at:
- **URL**: http://localhost:81
- **Default Credentials**:
  - Email: `admin@example.com`
  - Password: `changeme`

**Important**: Change these credentials immediately after first login!

### 2. Create Proxy Hosts

Configure the following proxy hosts in Nginx Proxy Manager:

#### Frontend (Atlas CMMS Web Interface)
- **Domain Names**: `your-domain.com`, `www.your-domain.com`
- **Scheme**: `http`
- **Forward Hostname/IP**: `atlas_frontend`
- **Forward Port**: `80`
- **Cache Assets**: ✅ Enabled
- **Block Common Exploits**: ✅ Enabled
- **Websockets Support**: ✅ Enabled

#### Backend API
- **Domain Names**: `api.your-domain.com` or `your-domain.com/api`
- **Scheme**: `http`
- **Forward Hostname/IP**: `atlas_api`
- **Forward Port**: `8080`
- **Block Common Exploits**: ✅ Enabled

#### MinIO Console (Optional)
- **Domain Names**: `minio.your-domain.com`
- **Scheme**: `http`
- **Forward Hostname/IP**: `atlas_minio`
- **Forward Port**: `9001`
- **Block Common Exploits**: ✅ Enabled

#### MinIO API (Optional)
- **Domain Names**: `storage.your-domain.com`
- **Scheme**: `http`
- **Forward Hostname/IP**: `atlas_minio`
- **Forward Port**: `9000`
- **Block Common Exploits**: ✅ Enabled

### 3. SSL Certificates

For each proxy host, configure SSL:

#### Let's Encrypt (Recommended)
1. Go to SSL tab in proxy host settings
2. Select "Request a new SSL Certificate"
3. Enable "Force SSL"
4. Enable "HTTP/2 Support"
5. Enable "HSTS Enabled"
6. Click "Save"

#### Custom SSL Certificate
1. Upload your certificate files
2. Configure SSL settings
3. Enable "Force SSL"

## Advanced Configuration

### Custom Nginx Configuration

For advanced needs, add custom Nginx configuration:

#### Frontend Custom Config
```nginx
# Add to Advanced > Custom Nginx Configuration
location /api/ {
    proxy_pass http://atlas_api:8080/api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
```

#### API Custom Config
```nginx
# Add to Advanced > Custom Nginx Configuration
client_max_body_size 100M;

# CORS headers for API
add_header Access-Control-Allow-Origin "$http_origin" always;
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization" always;
add_header Access-Control-Expose-Headers "Content-Length,Content-Range" always;

if ($request_method = 'OPTIONS') {
    add_header Access-Control-Max-Age 1728000;
    add_header Content-Type 'text/plain; charset=utf-8';
    add_header Content-Length 0;
    return 204;
}
```

### Access Control

Configure access control for sensitive endpoints:

1. **Admin Interface Protection**:
   - Create access list with your IP ranges
   - Apply to MinIO console proxy host

2. **API Rate Limiting**:
   - Use custom Nginx config for rate limiting
   - Example: `limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;`

## Environment Variables Update

Update your `.env` file for proxy setup:

```env
# Update these URLs to match your domain configuration
PUBLIC_API_URL=https://api.your-domain.com
PUBLIC_FRONT_URL=https://your-domain.com
VITE_API_BASE_URL=https://api.your-domain.com/api

# Or if using path-based routing
PUBLIC_API_URL=https://your-domain.com
PUBLIC_FRONT_URL=https://your-domain.com
VITE_API_BASE_URL=https://your-domain.com/api
```

## Security Best Practices

### 1. Change Default Credentials
- Update Nginx Proxy Manager admin credentials
- Use strong passwords for all services

### 2. Configure Firewall
- Only expose ports 80, 443, and 81 (admin)
- Block direct access to service ports (5432, 8080, 9000, 9001)

### 3. Regular Updates
- Keep Nginx Proxy Manager updated
- Update SSL certificates before expiration

### 4. Monitoring
- Enable access logs
- Monitor failed login attempts
- Set up alerts for certificate expiration

## Backup and Restore

### Backup Nginx Proxy Manager Configuration
```bash
# Create backup
docker exec nginx-proxy-manager tar -czf /tmp/npm-backup.tar.gz /data

# Copy backup from container
docker cp nginx-proxy-manager:/tmp/npm-backup.tar.gz ./backups/
```

### Restore Configuration
```bash
# Copy backup to container
docker cp ./backups/npm-backup.tar.gz nginx-proxy-manager:/tmp/

# Restore data
docker exec nginx-proxy-manager tar -xzf /tmp/npm-backup.tar.gz -C /
```

## Troubleshooting

### Common Issues

1. **502 Bad Gateway**:
   - Check if backend service is running
   - Verify service names in proxy configuration
   - Check Docker network connectivity

2. **SSL Certificate Issues**:
   - Verify domain DNS points to your server
   - Check port 80/443 accessibility
   - Review Let's Encrypt rate limits

3. **CORS Errors**:
   - Configure proper CORS headers in custom config
   - Ensure API URLs match frontend configuration

### Logs

View Nginx Proxy Manager logs:
```bash
docker logs nginx-proxy-manager
```

View service logs:
```bash
docker logs atlas_api
docker logs atlas_frontend
```

## Additional Resources

- [Nginx Proxy Manager Documentation](https://nginxproxymanager.com/guide/)
- [Let's Encrypt Documentation](https://letsencrypt.org/docs/)
- [Atlas CMMS Configuration Guide](https://grashjs.github.io/user-guide/)