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:
| Container | Port | Serves |
|---|---|---|
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.
Layout 1 — one address for everything (recommended)
The browser uses one address, for example https://alerts.example.com, for the UI and the API. Only your proxy is reachable from outside.
| Path | Send it to | Why |
|---|---|---|
/socket.io/ | Backend 9000 | Required. 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 9000 | Recommended. 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 8080 | The 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)
API_URL with /apiYour 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_URL | UI requests go to | |
|---|---|---|
https://alerts.example.com | https://alerts.example.com/api/alerts | Correct |
https://alerts.example.com/api | https://alerts.example.com/api/api/alerts | Wrong: 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) andAPI_URLmust start withhttps://, 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_ORIGINSon 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 showssocket.iorequests answered with301,400or502instead of101 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
| Field | Value |
|---|---|
| Domain Names | alerts.example.com |
| Scheme | http |
| Forward Hostname / IP | tobealert-frontend when Nginx Proxy Manager is on the same Docker network as ToBeAlert; otherwise the ToBeAlert server's address |
| Forward Port | 8080 (container) on the same Docker network; otherwise the frontend's host port (80 in the install examples) |
Options, as they appear under the fields:
| Option | Recommendation | Why |
|---|---|---|
| Cache Assets | Off | The 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 Exploits | Off (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 Support | On | Needed 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:
| Location | Forward to |
|---|---|
/api/ | backend 9000 |
/socket.io/ | backend 9000 |
Leave the forward hostname without a path. For layout 2, skip this tab.
SSL tab
| Option | Recommendation |
|---|---|
| SSL Certificate | Request a Let's Encrypt certificate or pick one you uploaded |
| Force SSL | On. Plain HTTP requests are redirected to HTTPS |
| HTTP/2 Support | On. It does not affect WebSockets |
| HSTS Enabled | Only 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 Subdomains | Only 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:
| Header | Value | Used for |
|---|---|---|
Host | The 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-For | Client address, appended | The user's address in the audit log, and the per-address limits on password change and password recovery |
X-Forwarded-Proto | https | Scheme of links built from the request |
Upgrade / Connection | Passed 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 (noports:, or bind it to127.0.0.1): a client that reaches port 9000 directly could write its ownX-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=falseon 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.
Public address and generated links
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 want | Do 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 applications | Forward /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 proxy | Not supported. The UI loads its files from /tobealert/… and calls /api/… at absolute paths. Use a dedicated host name |
Timeouts
| Request | How long it can take | Proxy setting |
|---|---|---|
| Regular API calls | The UI gives up after 15 seconds | Default timeouts are fine |
| Running the Performance diagnostics | Up to 2 minutes | Read timeout of at least 120 s (300 s recommended) on /api/ |
| Hotfix bundle upload | The 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 s | Idle timeout of 60 s or more (1 h recommended) |
Request body size
| Upload | Maximum accepted by ToBeAlert |
|---|---|
| Hotfix bundle | 50 MB |
| CMDB import (Importing from a CMDB) | 20 MB |
| Service topology import | 2 MB |
| Offline license file, webhook payload | 256 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
524when 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 hits524. 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.htmland 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 oneset_real_ip_fromline per Cloudflare address range.
Checklist
Run it after every change to the proxy. Replace alerts.example.com with your host name.
- UI:
curl -sI https://alerts.example.com/tobealert/→200. Openhttps://alerts.example.comin a browser: it lands on/tobealertand shows the login page. - API through the proxy:
curl -s https://alerts.example.com/api/health→ JSON with one entry per component (200when everything is healthy). - Socket.IO through the proxy:
curl -s "https://alerts.example.com/socket.io/?EIO=4&transport=polling"→ a line starting with0{"sid":. A redirect or an HTML page means/socket.io/is not going to the backend. - UI configuration:
curl -s https://alerts.example.com/tobealert/config.json | grep apiUrl→"apiUrl": "https://alerts.example.com/api/"(layout 1). - WebSocket in the browser: open a shared instruction page, press F12 → Network → filter WS: the
socket.iorequest shows status101, and the viewer counter shows at least1. - Large upload: import a CMDB file over 1 MB, or upload a hotfix bundle: no
413. - Searches: run a few TQL searches your operators use, including values with quotes, slashes or URLs: no
403. - Links: send a test notification and open its alert link: it opens
https://alerts.example.com/tobealert/dash?alertId=…. - Client address: after a login, the audit log events record the user's address (
remoteIp), not the proxy's.
If something fails
| Symptom | Cause | Fix |
|---|---|---|
| UI loads, but login or data fails; console shows mixed content or blocked requests | API_URL still http://… or still points at port 9000 the browser cannot reach | Layout 1: API_URL = the public https:// address, no port, no /api. Recreate the frontend |
Requests go to /api/api/… | API_URL ends with /api | Remove /api from API_URL |
Viewer counter stuck at 0; console WebSocket connection … failed | WebSockets off, or /socket.io/ sent to the frontend | Turn WebSocket support on and route /socket.io/ to the backend |
413 Request Entity Too Large on an import or a hotfix upload | Body 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 bundle | Proxy timeout shorter than the request | Read and send timeouts of 300 s on /api/ |
403 on some searches only | Block Common Exploits or a WAF rule matched the search in the URL | Turn the option off, or add an exception for this host name |
Links in notifications have no host or point at localhost | Backend BASE_URL empty or wrong | Set the backend's BASE_URL to the public address and restart the backend |
| Old screens after an upgrade or a hotfix | A 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 row | Send /api/ to the backend; restore the visitor's address on the first proxy |
Related
- Docker — the Compose stack these examples extend
- Kubernetes — Services and environment variables for an Ingress
- HTTPS and TLS — TLS without a proxy of your own
- Settings & environment variables —
BASE_URL,API_URL,TRUST_PROXY_HEADERS,CORS_ORIGINS - Hotfix bundles — uploads through the proxy