Skip to main content
Version: 1.4 (Current)

Behind a reverse proxy

This page is for you if ToBeAlert sits behind a proxy you already run: Nginx Proxy Manager, Traefik, Caddy, HAProxy, Apache, nginx, a cloud or hardware load balancer, a Kubernetes Ingress, or Cloudflare. Your proxy terminates TLS and ToBeAlert stays on plain HTTP behind it.

If nothing terminates TLS for ToBeAlert yet, HTTPS and TLS adds a small TLS container to the Compose stack instead.


What the proxy talks to​

ToBeAlert has two containers that matter here:

ContainerPortServes
Frontend (tobealert-frontend)8080 (HTTP)The Web UI under /tobealert/. It also forwards /api/ to the backend by itself
Backend (tobealert-backend)9000 (HTTP, or HTTPS with SSL_CERT / SSL_KEY)The API (/api/) and the live connections (Socket.IO under /socket.io/)

Point the proxy at the frontend. The backend does not serve the UI: a proxy whose main route goes to port 9000 shows no Web UI. Use the frontend's host port (80 in the install examples) or, when the proxy runs on the same Docker network, tobealert-frontend:8080.

Where the browser sends API calls is a separate choice, set by the frontend variable API_URL. Pick one of the two layouts below.

The browser uses one address, for example https://alerts.example.com, for the UI and the API. Only your proxy is reachable from outside.

PathSend it toWhy
/socket.io/Backend 9000Required. The frontend container does not forward it: a request for /socket.io/ that reaches the frontend is redirected to the UI and the live connection never opens
/api/Backend 9000Recommended. The frontend can forward it too, but then requests over 1 MB are refused with 413 (except hotfix bundle uploads), requests longer than 60 s end in 504, and the backend records your proxy's address instead of the user's
Everything else (/, /tobealert/…)Frontend 8080The Web UI, its config.json and the files of hotfix UI fixes

Settings for this layout:

  tobealert-backend:
environment:
BASE_URL: https://alerts.example.com # public address, used for generated links
# no "ports:" when the proxy runs on the same Docker network;
# "127.0.0.1:9000:9000" when the proxy runs on the host itself

tobealert-frontend:
environment:
BASE_URL: https://alerts.example.com
API_URL: https://alerts.example.com # no port, no /api
BACKEND_SERVICE: tobealert-backend
BACKEND_PORT: "9000"
# no "ports:" when the proxy runs on the same Docker network;
# otherwise keep "80:8080" (or "127.0.0.1:8080:8080" for a proxy on the host)
Do not end API_URL with /api

Your proxy publishes the backend under /api/ (https://alerts.example.com/api/… → backend), but the frontend variable API_URL takes the address without /api. When the frontend container starts it writes apiUrl = API_URL + /api/ into /tobealert/config.json, and the UI sends every request to that address.

API_URLUI requests go to
https://alerts.example.comhttps://alerts.example.com/api/alertsCorrect
https://alerts.example.com/apihttps://alerts.example.com/api/api/alertsWrong: every request fails

The backend can stay on plain HTTP: TLS ends at your proxy. Recreate the frontend after changing API_URL (its config.json is written when the container starts).

Layout 2 — UI behind the proxy, API on its own port​

This is what the install pages set up: API_URL is http(s)://your-server:9000, so the browser calls the backend port directly and your proxy only carries the UI. It works, with these conditions:

  • Port 9000 must be reachable from every user's browser.
  • When the UI is opened over HTTPS, the backend needs its own certificate (SSL_CERT / SSL_KEY) and API_URL must start with https://, otherwise the browser blocks the API calls as mixed content. See HTTPS and TLS.
  • WebSockets, body size and timeouts of your proxy do not matter for the API in this layout: those requests never pass through it.
  • If you restrict CORS_ORIGINS on the backend, it must include the UI address (UI and API are different origins here).

WebSockets​

Turn WebSocket support on for the route that reaches the backend (/socket.io/).

What uses it today: the live viewer counter in the header of a shared instruction page (the people icon with a number). The alerts dashboard, the badge counters and the other lists refresh by regular HTTP requests at the user's refresh interval, so they keep working without WebSockets.

When WebSockets do not get through (option off, or /socket.io/ not routed to the backend):

  • The viewer counter stays at 0.
  • The browser console (F12 → Console) repeats an error such as WebSocket connection to 'wss://alerts.example.com/socket.io/?EIO=4&transport=websocket' failed, and the Network tab shows socket.io requests answered with 301, 400 or 502 instead of 101 Switching Protocols.

The connection exchanges a ping every 25 seconds, so any idle timeout of 60 seconds or more keeps it open.


Nginx Proxy Manager​

Create a Proxy Host for ToBeAlert.

Details tab​

FieldValue
Domain Namesalerts.example.com
Schemehttp
Forward Hostname / IPtobealert-frontend when Nginx Proxy Manager is on the same Docker network as ToBeAlert; otherwise the ToBeAlert server's address
Forward Port8080 (container) on the same Docker network; otherwise the frontend's host port (80 in the install examples)

Options, as they appear under the fields:

OptionRecommendationWhy
Cache AssetsOffThe frontend container already sends the right cache headers: the UI's index.html is never cached, scripts and styles are revalidated on every load (an unchanged file costs a 304), and fonts and images are versioned and cached for a year. This option replaces those headers: it caches scripts, styles and images on the proxy and tells browsers to keep them for weeks. The release files carry the version in their URL, so a normal upgrade still loads the new ones, but files without a version in the URL (favicon, bundled pages and libraries) can stay old after an upgrade or a hotfix, and nothing gets faster
Block Common ExploitsOff (or test first)It compares each URL and query string with fixed patterns (SQL fragments, ../, <script>, =http:// and similar) and answers 403 Forbidden before ToBeAlert sees the request. Searches and filters travel in the query string, so a TQL search or a filter value with those characters can be blocked by accident; the user only sees a failed search. ToBeAlert checks its own input. If your policy requires it on, run the searches your operators use (checklist below)
Websockets SupportOnNeeded for /socket.io/ (see WebSockets). It also applies to the custom locations of this proxy host

Custom locations tab (layout 1)​

Add two locations, both Scheme http, Forward Hostname / IP tobealert-backend (same Docker network) or the server's address, Forward Port 9000:

LocationForward to
/api/backend 9000
/socket.io/backend 9000

Leave the forward hostname without a path. For layout 2, skip this tab.

SSL tab​

OptionRecommendation
SSL CertificateRequest a Let's Encrypt certificate or pick one you uploaded
Force SSLOn. Plain HTTP requests are redirected to HTTPS
HTTP/2 SupportOn. It does not affect WebSockets
HSTS EnabledOnly when this host name will always be served over HTTPS. Browsers then refuse plain HTTP for that name, on every port, for a long time, and turning it off later does not undo that in browsers that already saw it. In layout 2 this includes the API port: the backend must have TLS
HSTS SubdomainsOnly if every subdomain of the name is HTTPS too

Advanced tab​

client_max_body_size 64m;
proxy_read_timeout 300s;
proxy_send_timeout 300s;

The body size covers hotfix bundle uploads (up to 50 MB) and CMDB imports (up to 20 MB). The timeouts cover the longest requests (see Timeouts).


Headers and client address​

Your proxy should pass:

HeaderValueUsed for
HostThe host name the user typed (keep it; do not replace it with the upstream name)Redirects and links that the frontend and backend build from the request
X-Forwarded-ForClient address, appendedThe user's address in the audit log, and the per-address limits on password change and password recovery
X-Forwarded-ProtohttpsScheme of links built from the request
Upgrade / ConnectionPassed through on /socket.io/WebSockets

X-Forwarded-Host is not needed: ToBeAlert reads the host from Host.

The backend setting TRUST_PROXY_HEADERS (default true, see Settings) makes the backend take the client address and the scheme from X-Forwarded-For and X-Forwarded-Proto set by one proxy in front of it:

  • Layout 1 with /api/ sent to the backend: the backend records the address your proxy saw, which is what you want. Do not publish the backend port to users (no ports:, or bind it to 127.0.0.1): a client that reaches port 9000 directly could write its own X-Forwarded-For.
  • /api/ through the frontend container: there are two proxies in a row (yours, then the frontend's nginx), so the backend records the address of your proxy.
  • Layout 2: browsers reach port 9000 with no proxy in front. Set TRUST_PROXY_HEADERS=false on the backend so a client cannot fake its address.
  • Several proxies in a row (for example Cloudflare → your proxy → ToBeAlert): restore the visitor's address on your proxy first (see Cloudflare); the backend trusts one hop only.

Set the backend's BASE_URL to the public address users open, without a path: https://alerts.example.com. The backend builds absolute links from it: the alert link %href% in notifications (https://alerts.example.com/tobealert/dash?alertId=…), the links in password recovery emails, and the Webhook URL shown for custom webhooks. Notifications are sent by background workers, which never see a browser request: without BASE_URL their links have no host. Password recovery is only offered when BASE_URL is set.

The frontend's BASE_URL and API_URL must be the same public address in layout 1 (API_URL without a port and without /api; the UI appends /api/ itself).


Path: ToBeAlert lives under /tobealert​

The UI is always served under /tobealert/; that path is fixed in the image. The root / answers with a redirect to /tobealert (a relative redirect, so it keeps your scheme, host and port).

You wantDo this
ToBeAlert on its own host name (https://alerts.example.com)Forward everything, as in the examples. Users opening the root land on /tobealert
ToBeAlert on a host name shared with other applicationsForward /tobealert/, /api/ and /socket.io/ to ToBeAlert, as in layout 1. Those paths cannot be used by another application on that host name
ToBeAlert under another path (/monitoring/), or with the /tobealert prefix removed or rewritten by the proxyNot supported. The UI loads its files from /tobealert/… and calls /api/… at absolute paths. Use a dedicated host name

Timeouts​

RequestHow long it can takeProxy setting
Regular API callsThe UI gives up after 15 secondsDefault timeouts are fine
Running the Performance diagnosticsUp to 2 minutesRead timeout of at least 120 s (300 s recommended) on /api/
Hotfix bundle uploadThe UI waits up to 5 minutes (50 MB over a slow link)Send and read timeout of 300 s on /api/
WebSocket on /socket.io/Stays open while the page is open; ping every 25 sIdle timeout of 60 s or more (1 h recommended)

Request body size​

UploadMaximum accepted by ToBeAlert
Hotfix bundle50 MB
CMDB import (Importing from a CMDB)20 MB
Service topology import2 MB
Offline license file, webhook payload256 KB

Set your proxy to 64 MB (or more) so it is never stricter than ToBeAlert. The frontend container accepts 64 MB on the hotfix upload path and 1 MB on the rest of /api/; that is why layout 1 sends /api/ straight to the backend.


Examples​

All examples use layout 1, the host name alerts.example.com and a proxy on the same Docker network as ToBeAlert (tobealert-frontend:8080, tobealert-backend:9000). For a proxy on another machine, use the ToBeAlert server's address and the published ports instead.

nginx​

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}

server {
listen 443 ssl;
http2 on; # nginx 1.25.1+; older versions: listen 443 ssl http2;
server_name alerts.example.com;

ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;

client_max_body_size 64m;

location /api/ {
proxy_pass http://tobealert-backend:9000;
proxy_http_version 1.1;
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 300s;
proxy_send_timeout 300s;
}

location /socket.io/ {
proxy_pass http://tobealert-backend:9000;
proxy_http_version 1.1;
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_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 1h;
}

location / {
proxy_pass http://tobealert-frontend:8080;
proxy_http_version 1.1;
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;
}
}

server {
listen 80;
server_name alerts.example.com;
return 301 https://$host$request_uri;
}

Write the proxy_set_header lines in every location: nginx drops the server-level ones in a location that sets any of its own.

Traefik (Compose labels)​

  tobealert-frontend:
labels:
- traefik.enable=true
- traefik.docker.network=tobealert-network
- traefik.http.routers.tobealert.rule=Host(`alerts.example.com`)
- traefik.http.routers.tobealert.entrypoints=websecure
- traefik.http.routers.tobealert.tls=true
- traefik.http.services.tobealert.loadbalancer.server.port=8080

tobealert-backend:
labels:
- traefik.enable=true
- traefik.docker.network=tobealert-network
- traefik.http.routers.tobealert-api.rule=Host(`alerts.example.com`) && (PathPrefix(`/api/`) || PathPrefix(`/socket.io/`))
- traefik.http.routers.tobealert-api.entrypoints=websecure
- traefik.http.routers.tobealert-api.tls=true
- traefik.http.services.tobealert-api.loadbalancer.server.port=9000

Traefik must be attached to tobealert-network. It passes WebSockets and the X-Forwarded-* headers by itself and has no body size limit by default. The longer rule wins, so /api/ and /socket.io/ go to the backend. If large uploads over slow links fail, raise respondingTimeouts.readTimeout of the websecure entry point (Traefik v3 defaults to 60 s). Add your certificate resolver to both routers (…tls.certresolver=…).

Caddy​

alerts.example.com {
handle /api/* {
reverse_proxy tobealert-backend:9000
}
handle /socket.io/* {
reverse_proxy tobealert-backend:9000
}
handle {
reverse_proxy tobealert-frontend:8080
}
}

Caddy gets the certificate, passes WebSockets and sets X-Forwarded-For / X-Forwarded-Proto by itself, with no body size limit by default.

Apache httpd​

Modules: proxy, proxy_http, proxy_wstunnel, rewrite, headers, ssl.

<VirtualHost *:443>
ServerName alerts.example.com

SSLEngine on
SSLCertificateFile /etc/ssl/alerts/fullchain.pem
SSLCertificateKeyFile /etc/ssl/alerts/privkey.pem

ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyTimeout 300

# WebSocket upgrade for Socket.IO (mod_proxy_wstunnel)
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/socket.io/(.*) ws://tobealert-backend:9000/socket.io/$1 [P,L]

ProxyPass /socket.io/ http://tobealert-backend:9000/socket.io/
ProxyPassReverse /socket.io/ http://tobealert-backend:9000/socket.io/
ProxyPass /api/ http://tobealert-backend:9000/api/
ProxyPassReverse /api/ http://tobealert-backend:9000/api/
ProxyPass / http://tobealert-frontend:8080/
ProxyPassReverse / http://tobealert-frontend:8080/
</VirtualHost>

Apache uses the first matching ProxyPass, so keep the specific paths above /. It adds X-Forwarded-For by itself. On Apache 2.4.47 or later you can replace the three rewrite lines with upgrade=websocket at the end of the /socket.io/ ProxyPass line.

HAProxy​

defaults
mode http
timeout connect 5s
timeout client 300s
timeout server 300s
timeout tunnel 1h

frontend https
bind :443 ssl crt /etc/haproxy/certs/alerts.example.com.pem alpn h2,http/1.1
option forwardfor
http-request set-header X-Forwarded-Proto https
acl tobealert_backend_path path_beg /api/ /socket.io/
use_backend tobealert_backend if tobealert_backend_path
default_backend tobealert_frontend

backend tobealert_frontend
server frontend tobealert-frontend:8080

backend tobealert_backend
server backend tobealert-backend:9000

HAProxy passes WebSockets by itself; timeout tunnel is the idle timeout of an open WebSocket.

Kubernetes Ingress (ingress-nginx)​

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: tobealert
namespace: tobealerta-interno
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "64m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
spec:
ingressClassName: nginx
tls:
- hosts: [alerts.example.com]
secretName: tobealert-tls
rules:
- host: alerts.example.com
http:
paths:
- path: /api/
pathType: Prefix
backend:
service: { name: tobealerta-backend-svc, port: { number: 9000 } }
- path: /socket.io/
pathType: Prefix
backend:
service: { name: tobealerta-backend-svc, port: { number: 9000 } }
- path: /
pathType: Prefix
backend:
service: { name: tobealerta-frontend-svc, port: { number: 8080 } }

ingress-nginx passes WebSockets without extra annotations. Set the frontend's BASE_URL and API_URL, and the backend's BASE_URL, to https://alerts.example.com (Kubernetes). Service names are the ones from the Kubernetes install page.

Cloudflare​

When Cloudflare proxies the host name (orange cloud) in front of your own proxy:

  • WebSockets must be on for the zone (Network settings).
  • Cloudflare ends a request with error 524 when the origin takes more than 100 seconds to answer. A Performance diagnostics run can take up to 2 minutes; run it from a path that does not go through Cloudflare if it hits 524. An open WebSocket is not affected (it pings every 25 s).
  • The request body limit of your Cloudflare plan applies to uploads (100 MB on the smallest plans, above the 50 MB of a hotfix bundle).
  • Do not add Cache Everything rules for this host name, and turn off features that rewrite scripts (such as Rocket Loader) for it: the UI must receive its own index.html and scripts unchanged.
  • Use the SSL/TLS mode Full (strict) with a valid certificate on your proxy.
  • Restore the visitor's address on your proxy, otherwise ToBeAlert records Cloudflare's address. With nginx: real_ip_header CF-Connecting-IP; plus one set_real_ip_from line per Cloudflare address range.

Checklist​

Run it after every change to the proxy. Replace alerts.example.com with your host name.

  1. UI: curl -sI https://alerts.example.com/tobealert/ → 200. Open https://alerts.example.com in a browser: it lands on /tobealert and shows the login page.
  2. API through the proxy: curl -s https://alerts.example.com/api/health → JSON with one entry per component (200 when everything is healthy).
  3. Socket.IO through the proxy: curl -s "https://alerts.example.com/socket.io/?EIO=4&transport=polling" → a line starting with 0{"sid":. A redirect or an HTML page means /socket.io/ is not going to the backend.
  4. UI configuration: curl -s https://alerts.example.com/tobealert/config.json | grep apiUrl → "apiUrl": "https://alerts.example.com/api/" (layout 1).
  5. WebSocket in the browser: open a shared instruction page, press F12 → Network → filter WS: the socket.io request shows status 101, and the viewer counter shows at least 1.
  6. Large upload: import a CMDB file over 1 MB, or upload a hotfix bundle: no 413.
  7. Searches: run a few TQL searches your operators use, including values with quotes, slashes or URLs: no 403.
  8. Links: send a test notification and open its alert link: it opens https://alerts.example.com/tobealert/dash?alertId=….
  9. Client address: after a login, the audit log events record the user's address (remoteIp), not the proxy's.

If something fails​

SymptomCauseFix
UI loads, but login or data fails; console shows mixed content or blocked requestsAPI_URL still http://… or still points at port 9000 the browser cannot reachLayout 1: API_URL = the public https:// address, no port, no /api. Recreate the frontend
Requests go to /api/api/…API_URL ends with /apiRemove /api from API_URL
Viewer counter stuck at 0; console WebSocket connection … failedWebSockets off, or /socket.io/ sent to the frontendTurn WebSocket support on and route /socket.io/ to the backend
413 Request Entity Too Large on an import or a hotfix uploadBody limit of your proxy, or /api/ going through the frontend container (1 MB)client_max_body_size 64m (or the equivalent) and /api/ to the backend
504 (or 524 with Cloudflare) when running the diagnostics or uploading a bundleProxy timeout shorter than the requestRead and send timeouts of 300 s on /api/
403 on some searches onlyBlock Common Exploits or a WAF rule matched the search in the URLTurn the option off, or add an exception for this host name
Links in notifications have no host or point at localhostBackend BASE_URL empty or wrongSet the backend's BASE_URL to the public address and restart the backend
Old screens after an upgrade or a hotfixA cache on the proxy or the CDN (Cache Assets, Cache Everything)Turn the cache off for this host name and purge it
Audit log shows the proxy's address/api/ goes through the frontend container, or several proxies in a rowSend /api/ to the backend; restore the visitor's address on the first proxy