OliveTin/docs/modules/ROOT/pages/reverse-proxies/intro.adoc

[#reverse-proxies]
= 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.

[#proxy-guide]
== 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 xref:reference/network-ports.adoc[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. xref:reverse-proxies/apache.adoc[Apache]) and xref:troubleshooting/err-websocket-connection.adoc[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:

* xref:reverse-proxies/nginx.adoc[Nginx] - Configure Nginx as a reverse proxy
* xref:reverse-proxies/apache.adoc[Apache] - Configure Apache as a reverse proxy
* xref:reverse-proxies/caddy.adoc[Caddy] - Configure Caddy as a reverse proxy
* xref:reverse-proxies/traefik.adoc[Traefik] - Configure Traefik as a reverse proxy
* xref:reverse-proxies/haproxy.adoc[HAProxy] - Configure HAProxy as a reverse proxy
* xref:reverse-proxies/nginx_proxy_manager.adoc[Nginx Proxy Manager] - Configure NPM as a reverse proxy
* xref:security/trusted_header.adoc[Use trusted headers] - Authenticate users via reverse proxy headers
* xref:reference/network-ports.adoc[Understand network ports] - Learn about OliveTin's port configuration