gree-controller/docs/REVERSE_PROXY.md

Reverse proxy

The web UI supports HTTPS/WSS and sub-path deployments. The server honors GREE_CONTROLLER_BASE_PATH and also understands X-Forwarded-Prefix when a proxy strips the prefix before forwarding.

Root deployment

Proxy / to http://127.0.0.1:8787 and forward WebSocket upgrade headers. No controller setting is required.

Sub-path deployment

For a public path such as /gree, either:

• set GREE_CONTROLLER_BASE_PATH=/gree and proxy /gree to the controller without stripping the path, or
• strip /gree in the proxy and send X-Forwarded-Prefix: /gree.

Static assets, language packs, browser routes, API requests, PWA scope and WebSocket URLs use the effective base path.

nginx example (prefix stripped)

location /gree/ {
    proxy_pass http://127.0.0.1:8787/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /gree;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

For an Internet-facing endpoint, add TLS and proxy authentication. If the application token is enabled, avoid access-log formats that record query strings because the browser WebSocket connection includes the token in its URL.