# Hermes Dashboard Reverse Proxy with Nginx

## Quick Setup (Nginx + Basic Auth)

### 1. Install Dependencies
```bash
sudo apt update && sudo apt install -y nginx apache2-utils
```

### 2. Create Password File
```bash
# Generate password (will prompt for password twice)
sudo htpasswd -c /etc/nginx/.htpasswd <username>

# Or non-interactive:
echo -n '<username>:' | sudo tee /etc/nginx/.htpasswd
openssl passwd -apr1 '<password>' | sudo tee -a /etc/nginx/.htpasswd
```

### 3. Nginx Config (`/etc/nginx/sites-available/hermes-dashboard`)
```nginx
server {
    listen 80;
    server_name <your-domain-or-ip>;  # e.g., 111.230.53.30 or hermes.example.com

    location / {
        auth_basic "Hermes Dashboard";
        auth_basic_user_file /etc/nginx/.htpasswd;
        
        proxy_pass http://127.0.0.1:9119;
        # IMPORTANT: Use "localhost" for Host header, NOT $host
        # Dashboard validates Host header and rejects non-localhost values
        # This causes "Invalid Host header" error if set to $host
        proxy_set_header Host localhost;
        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;
        
        # WebSocket support (required for Chat TUI)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}
```

### 4. Enable & Reload
```bash
sudo ln -sf /etc/nginx/sites-available/hermes-dashboard /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### 5. Ensure Dashboard Running
```bash
hermes dashboard --no-open --port 9119
```

## Access
- URL: `http://<domain-or-ip>`
- Auth: Browser popup for username/password

## Commands
```bash
sudo systemctl status nginx
sudo systemctl restart nginx
hermes dashboard --status
hermes dashboard --stop
```

## Cleanup (Remove Reverse Proxy)
```bash
# Stop services
hermes dashboard --stop
sudo systemctl stop nginx
sudo systemctl disable nginx

# Remove config files
sudo rm -f /etc/nginx/sites-available/hermes-dashboard
sudo rm -f /etc/nginx/sites-enabled/hermes-dashboard
sudo rm -f /etc/nginx/.htpasswd
```

## HTTPS (Optional)
Use Certbot for Let's Encrypt:
```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d hermes.example.com
```

## Pitfalls

### Invalid Host Header Error
If you see `{"detail":"Invalid Host header. Dashboard requests must use the hostname the server was bound to."}`:
- **Cause**: Nginx is passing `$host` (the public domain/IP) but Dashboard only accepts `localhost`
- **Fix**: Change `proxy_set_header Host $host;` to `proxy_set_header Host localhost;`

### Domain Requires ICP Filing (China)
If accessing via domain in China triggers ICP filing requirement:
- **Solution**: Use IP address directly instead of domain
- Update `server_name` to the server's public IP

### Security Notes
- Dashboard has NO built-in password auth
- Without reverse proxy, anyone with network access can see API keys
- Always use reverse proxy + basic auth for remote access
- Consider SSH port forwarding as a more secure alternative