Reverse Proxies

This section of the documentation has a few examples of reverse proxy configurations for popular reverse proxy servers.

Configuring a reverse proxy server for OliveTin is entirely optional. If you don’t want to use a reverse proxy, you can skip this section.

Reverse Proxy general guide

It’s common to put OliveTin behind a reverse proxy, for authentication, customizing the OliveTin address/path, or for a variety of other reasons.

DNS name vs Path based proxies

DNS Name based virtual hosts (eg: olivetin.example.com ) are easier to setup and configure than path based virtual hosts (eg: www.example.com/utils/OliveTin), because path based virtual hosts need to take care mangle OliveTin paths without breaking things.

  • If using a path based reverse proxies, you may need to set externalRestAddress manually to something like; http://example.com/utils/OliveTin in the OliveTin config.yaml.

  • If using DNS Name based reverse proxies, then you should not need to change anything in config.yaml

Which port?

If you look at OliveTin startup logs, you will see OliveTin starting services on several ports. For most users, even under reverse proxy configurations, just proxying port 1337 should be all that is needed. To better understand why OliveTin uses several internal ports by default, see network-ports.

Handling websockets

OliveTin versions after 2023-08 use websockets instead of polling for updates. Ensure your proxy re-passes the Connection: Upgrade and Upgrade: websocket headers for the websocket path. In OliveTin 3k the websocket endpoint is api/olivetin.api.v1.OliveTinApiService/EventStream; when proxying the whole site (e.g. ProxyPass / or location /), that path is covered automatically.

Many reverse proxies use short default timeouts and will close long-lived websocket connections, causing disconnects (OliveTin will reconnect automatically). To avoid this, increase the websocket or proxy timeout in your reverse proxy—see the individual proxy pages (e.g. Apache) and Error Connecting to WebSocket for details.

General checklist

  • olivetin.example.com/* is all just HTTP traffic (port 1337)

    • olivetin.example.com/ should show the standard webui (port 1337)

    • olivetin.example.com/webUiSettings.json should return a JSON file generated by OliveTin that sets up the web interface. (port 1337)

    • olivetin.example.com/api should show the REST based API. (port 1337)

  • The websocket (e.g. api/olivetin.api.v1.OliveTinApiService/EventStream in OliveTin 3k) should be a websocket connection upgrade.

What’s Next?

Choose your reverse proxy and follow the configuration guide: