Configure a reverse proxy
A reverse proxy presents SmartAGT under a public name, for example https://smartagt.example.org, and forwards the requests to the Frontend. This page describes what SmartAGT expects from the proxy. Setting the proxy up follows the documentation of your proxy.
In a cluster, the reverse proxy presents SmartAGT under a public name, for example https://smartagt.example.org, and spreads the requests across the Frontend nodes. This page describes what SmartAGT expects from the proxy. Setting the proxy up follows the documentation of your proxy.
The public name is the address your users see on your private network. A reverse proxy forwards requests without replacing this network: Network exposure.
Requirements
| Requirement | Expected by SmartAGT |
|---|---|
| Link to the Frontend | HTTPS to port 9000, or the configured port, open for inbound traffic from the proxy only in the server firewall. |
| Client address | Forwarded through X-Forwarded-For (or X-Real-IP) and X-Forwarded-Proto. |
| Declared proxy | Proxy addresses in trusted_proxies: without them, SmartAGT ignores the forwarded headers. |
| Streamed responses | Assistant responses arrive as a stream: buffering disabled, read timeout of at least 300 s. |
| Request size | Suited to the documents uploaded by users. |
| WebSocket | Not used. |
| Requirement | Expected by SmartAGT |
|---|---|
| Link to the Frontend | HTTPS to port 9000 of every Frontend node, open for inbound traffic from the proxy only, node certificate verified by your authority. |
| Distribution | Across the Frontend nodes, without session affinity: every node serves any session. |
| Health check | TCP connection to port 9000 of every node. |
| Client address | Forwarded through X-Forwarded-For (or X-Real-IP) and X-Forwarded-Proto. |
| Declared proxy | Proxy addresses in trusted_proxies, on every Frontend node: without them, SmartAGT ignores the forwarded headers. |
| Streamed responses | Assistant responses arrive as a stream: buffering disabled, read timeout of at least 300 s. |
| Request size | Suited to the documents uploaded by users. |
| WebSocket | Not used. |
Procedure
1. Declare the proxy in SmartAGT
In the Frontend YAML, add the proxy address and the public origin, then restart the Frontend service: Operations.
On every Frontend node, add the proxy address and the public origin to the Frontend YAML, then restart its service, one node after the other: Operations.
smartagt:
http:
server:
trusted_proxies: ["10.20.0.10/32"] # proxy address
cors:
allow_origins: ["https://smartagt.example.org"] # public name
Expected result: the Frontend restarts without error.
2. Configure the proxy
Apply the requirements above in your proxy. Example for NGINX, to adapt:
server {
listen 443 ssl;
server_name smartagt.example.org;
ssl_certificate /etc/nginx/tls/public.crt;
ssl_certificate_key /etc/nginx/tls/public.key;
client_max_body_size 256m;
location / {
proxy_pass https://bff.internal.example.org:9000;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/nginx/tls/ca.crt;
proxy_ssl_server_name on;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 300s;
}
}
Apply the requirements above in your proxy. Example for NGINX, to adapt:
upstream smartagt_frontend {
server frontend-1.example.test:9000;
server frontend-2.example.test:9000;
}
server {
listen 443 ssl;
server_name smartagt.example.org;
ssl_certificate /etc/nginx/tls/public.crt;
ssl_certificate_key /etc/nginx/tls/public.key;
client_max_body_size 256m;
location / {
proxy_pass https://smartagt_frontend;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/nginx/tls/ca.crt;
proxy_ssl_name frontend.example.test;
proxy_ssl_server_name on;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 300s;
}
}
Behind an upstream, NGINX verifies every node under a single name, set by proxy_ssl_name: the certificate of every Frontend node carries this shared name.
Directive reference: NGINX proxy module.
Expected result:
- the sign-in page opens at
https://smartagt.example.org - a Smarty response is displayed progressively
Special cases
Public API or AI Gateway behind the proxy
Each listener declares its own proxies, in the Backend YAML, then the relevant service restarts:
| Listener | Upstream port | Backend YAML key |
|---|---|---|
| Public API | 8000 |
smartagt.http.public.trusted_proxies |
| AI Gateway | 8001 |
smartagt.gateway.server.trusted_proxies |
Use a separate public name per listener. AI Gateway only accepts IPv4 client addresses and refuses any call relayed by an undeclared proxy: Enable AI Gateway.
Several API nodes: the internal link
The internal link 8010, between the Frontend and the API, uses mutual TLS: an HTTP proxy that terminates TLS breaks it. Across several API nodes, use a load balancer in plain TCP passthrough (L4), then declare its name in smartagt.http.internal.url. With NGINX, a stream block at the top level of nginx.conf:
stream {
upstream smartagt_internal {
server api1.internal.example.org:8010;
server api2.internal.example.org:8010;
}
server {
listen 8010;
proxy_pass smartagt_internal;
}
}
Restrict this port to the Frontend servers.