Setting Up a Proxy for Stack

TLS, host headers, WebSocket forwarding, and the few proxy settings that actually matter.

Jaws Deploy Stack binds to plain HTTP by default. Production installs put Stack behind a reverse proxy that terminates TLS and forwards the requests. Almost any proxy works - nginx, IIS, Apache, HAProxy.

What the proxy needs to do

Three things, in order of how often they trip people up:

// Proxy requirements

Get these right and Stack works

  • Forward the Host header as-is. Stack uses it to build absolute URLs in emails and links.
  • Forward X-Forwarded-Proto so Stack knows requests are arriving over HTTPS. Without this, generated links use http://.
  • Allow WebSocket upgrades. Live deployment logs use WebSockets. Without upgrade support, logs degrade to slow polling.
  • Bump body size limits. Package uploads can be hundreds of MB; the proxy's default request size is usually too small.
  • Disable response buffering on /api/.../logs/stream so live logs stream rather than chunk.
// nginx example

Minimal nginx config that ticks the boxes

Replace deploy.acme.internal with your hostname and point proxy_pass at the Stack bind address.

server {
    listen 443 ssl http2;
    server_name deploy.acme.internal;

    ssl_certificate     /etc/ssl/deploy.crt;
    ssl_certificate_key /etc/ssl/deploy.key;

    client_max_body_size 2g;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For   $remote_addr;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        proxy_read_timeout 600s;
    }

    location /api/v1/deployments/stream {
        proxy_pass http://127.0.0.1:8080;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}