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
The origin matches the public address seen by the browser, without the internal Frontend port: CORS. To also change the internal port, see Change the ports.
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;
}
}
ca.crt is the authority of your certificate or, with the certificate generated by SmartAGT, its exported root.
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
Proxy on the same server
When the proxy runs on the SmartAGT server, restrict the Frontend and AI Gateway listeners to the loopback: only requests going through the proxy reach them. Use 127.0.0.1 and not localhost: a proxy reaching AI Gateway through ::1 would be refused, because AI Gateway only accepts IPv4 clients.
In the Frontend YAML:
smartagt:
http:
server:
host: "127.0.0.1"
trusted_proxies: ["127.0.0.1/32"]
In the Backend YAML, if AI Gateway is enabled:
smartagt:
gateway:
server:
host: "127.0.0.1"
trusted_proxies: ["127.0.0.1/32"]
Restart the services concerned: Operations. In the proxy, target https://127.0.0.1:9000 and keep certificate verification. The certificate generated by SmartAGT covers localhost and 127.0.0.1: with NGINX, proxy_ssl_trusted_certificate points to its exported root and proxy_ssl_name localhost. With your own certificates, use your authority and a name present in the certificate.
Ports 8010 and 8011 never go through the proxy.
Expected result: ss -ltnp shows ports 9000 and 8001 on 127.0.0.1 only, and the login page opens through the public name.
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.