# How to Configure Reverse Proxy WebSocket Upgrades for TREK: Nginx and Caddy Setup

> Configure Nginx or Caddy for WebSocket upgrades to enable TREK's real-time features. Learn to forward headers, set timeouts, and manage upload limits for seamless collaboration.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-06-26

---

**To enable WebSocket upgrades behind a reverse proxy, you must forward the `Upgrade` and `Connection` headers in Nginx or rely on Caddy’s automatic upgrade detection, while setting extended timeouts and large upload limits to support TREK’s real-time collaboration and backup restore features.**

TREK relies on persistent WebSocket connections on the `/ws` endpoint for real-time collaboration. When deploying the application behind a TLS-terminating reverse proxy, proper configuration of reverse proxy WebSocket upgrades is essential to maintain connection stability and support large file uploads. The repository provides specific configuration examples in [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md) and related environment settings in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md).

## Why WebSocket Configuration Matters for TREK

TREK uses the `/ws` endpoint for persistent WebSocket connections that power real-time collaboration features. According to the repository's [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md), these connections require specific handling to prevent timeouts and ensure headers are forwarded correctly. Additionally, backup restore operations can exceed 500 MB, necessitating increased upload limits beyond standard defaults.

## Nginx Configuration for WebSocket Upgrades

When using Nginx as your reverse proxy, you must explicitly configure WebSocket upgrade headers and timeout values as documented in [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md).

### Complete Configuration Example

The following configuration handles both HTTP/HTTPS redirection and WebSocket-specific requirements:

```nginx
server {
    listen 80;
    server_name trek.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name trek.yourdomain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # WebSocket endpoint

    location /ws {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 86400;          # keep WS alive (24 h)

        client_max_body_size 500m;         # large backup restores

    }

    # All other traffic

    location / {
        proxy_pass http://localhost:3000;
        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;
        client_max_body_size 500m;
    }
}

```

### Key Directives Explained

**`proxy_set_header Upgrade $http_upgrade`**: This directive forwards the client's upgrade request, signaling Nginx to switch protocols from HTTP to WebSocket.

**`proxy_read_timeout 86400`**: Sets the timeout to 24 hours (86400 seconds) to keep WebSocket connections alive for long-running collaboration sessions, as implemented in [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md).

**`client_max_body_size 500m`**: Allows file uploads up to 500 MB to accommodate TREK's backup restore functionality.

## Caddy Configuration for WebSocket Upgrades

Caddy simplifies reverse proxy WebSocket upgrades by automatically detecting upgrade headers, though explicit upload limits remain necessary for large file operations.

### Automatic WebSocket Handling

For standard deployments, Caddy requires minimal configuration:

```caddy
trek.yourdomain.com {
    # Basic reverse proxy – Caddy auto-upgrades WebSockets

    reverse_proxy localhost:3000
}

```

### Handling Large File Uploads

To support backup restores exceeding standard limits, extend the configuration as documented in [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md):

```caddy
trek.yourdomain.com {
    request_body max_size 500mb
    reverse_proxy localhost:3000
}

```

## Environment Variables for Proxy Integration

TREK's runtime behavior depends on several environment variables that must align with your reverse proxy configuration. As documented in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md), these settings control HTTPS redirection and cookie security:

- **`FORCE_HTTPS`**: Enables HTTPS redirection when behind a proxy
- **`TRUST_PROXY`**: Allows TREK to trust `X-Forwarded-*` headers from the proxy
- **`COOKIE_SECURE`**: Ensures cookies are only transmitted over HTTPS
- **`ALLOWED_ORIGINS`**: Defines permitted CORS origins

These variables ensure that the proxy correctly forwards `X-Forwarded-Proto` and `X-Forwarded-For` headers, maintaining proper request context and security. The [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) file includes production-ready examples of these environment variables for proxy deployments.

## Summary

- **WebSocket upgrades require explicit header forwarding in Nginx** (`Upgrade` and `Connection` headers), while Caddy handles these automatically.
- **Set extended timeouts** (`proxy_read_timeout 86400` in Nginx) to prevent WebSocket disconnections during long collaboration sessions.
- **Configure large upload limits** (`client_max_body_size 500m` or `request_body max_size 500mb`) to support TREK's backup restore functionality.
- **Reference [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md)** for the complete configuration examples and [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md) for HTTPS-related environment variables.
- **Set `TRUST_PROXY` and `FORCE_HTTPS`** to ensure proper header forwarding and secure cookie handling when using [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) in production.

## Frequently Asked Questions

### Do I need special configuration for WebSocket support in Caddy?

No, Caddy automatically detects WebSocket upgrade requests and handles the header forwarding without explicit configuration. However, you must still configure `request_body max_size` if you plan to restore large backups through the application.

### What timeout value should I use for WebSocket connections in Nginx?

Set `proxy_read_timeout` to **86400 seconds** (24 hours) as specified in [`wiki/Reverse-Proxy.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Reverse-Proxy.md). This prevents Nginx from closing idle WebSocket connections during extended collaboration sessions while maintaining reasonable resource management.

### Why do I need to configure `client_max_body_size` for both location blocks?

Backup restore operations in TREK can exceed 500 MB, requiring the reverse proxy to accept large request bodies. Configuring this limit in both the `/ws` location and the general `/` location ensures that file uploads work correctly regardless of which endpoint handles the request.

### Which environment variables must be set when using a reverse proxy?

Set **`TRUST_PROXY`** to allow TREK to accept `X-Forwarded-For` and `X-Forwarded-Proto` headers, **`FORCE_HTTPS`** to enable HTTPS redirection, and **`COOKIE_SECURE`** to ensure secure cookie transmission. These settings are documented in [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md) and ensure proper integration with TLS-terminating proxies.