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

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 and related environment settings in 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, 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.

Complete Configuration Example

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

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.

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:

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:

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, 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 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 for the complete configuration examples and 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 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. 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 and ensure proper integration with TLS-terminating proxies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}