# Setting up Nginx as a Reverse Proxy

This guide explains how to configure Nginx to act as a reverse proxy for the TischlerCtrl server. This allows you to host the application on standard HTTP/HTTPS ports (80/443) and adds a layer of security.

## Prerequisites

-   A Linux server (Debian/Ubuntu/Raspberry Pi OS).
-   Root or sudo access.
-   TischlerCtrl server running on localhost (default port: `8080`).

## 1. Install Nginx

If Nginx is not already installed:

```bash
sudo apt update
sudo apt install nginx
```

## 2. Create Configuration File

Create a new configuration file for the site in `/etc/nginx/sites-available/`. We'll name it `tischlerctrl`.

```bash
sudo nano /etc/nginx/sites-available/tischlerctrl
```

Paste the following configuration using your actual domain name or IP address:

```nginx
server {
    listen 80;
    server_name your-domain.com; # Replace with your domain or IP address

    # Access logs
    access_log /var/log/nginx/tischlerctrl.access.log;
    error_log /var/log/nginx/tischlerctrl.error.log;

    location /agentapi/ {
        proxy_pass http://localhost:8080/; # Trailing slash strips /agentapi/
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        
        # Forwarding real client IP
        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;
    }
}
```

### Key Configuration Explained

-   **proxy_pass**: Forwards requests to your Node.js application running on port 8080.
-   **WebSocket Support**: These lines are **critical** for TischlerCtrl as it relies on WebSockets for real-time sensor data:
    ```nginx
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    ```

## 3. Enable the Site

Create a symbolic link to the `sites-enabled` directory to activate the configuration:

```bash
sudo ln -s /etc/nginx/sites-available/tischlerctrl /etc/nginx/sites-enabled/
```

## 4. Test and Reload Nginx

Test the configuration for syntax errors:

```bash
sudo nginx -t
```

If the test is successful (returns `syntax is ok`), reload Nginx:

```bash
sudo systemctl reload nginx
```

## 5. SSL Configuration (Recommended)

To secure your connection with HTTPS (especially important for authentication), use Certbot to automatically configure a free specific Let's Encrypt SSL certificate.

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

Certbot will automatically modify your Nginx configuration to force HTTPS redirection and manage the SSL certificates.

## 6. Update Client Configurations

Since you are serving the API under `/agentapi/`, you must update your agents' configuration to point to the new URL path.

### WebSocket URL Format

-   **Old (Direct):** `ws://server-ip:8080`
-   **New (Proxy):** `ws://your-domain.com/agentapi/` (or `wss://` if using SSL)

### Example for Tapo Agent (`config.toml`)

```toml
server_url = "ws://your-domain.com/agentapi/"
# Or with SSL:
# server_url = "wss://your-domain.com/agentapi/"
```

### Example for Environment Variables

For agents using `.env` files:

```bash
SENSOR_SERVER="ws://your-domain.com/agentapi/"
```