Deployment
Self-hosted Talqo deployment requirements.
Docker Compose
The talqo-deploy repository runs Talqo, Postgres, and Docling as one Compose project:
git clone https://github.com/Talqo/talqo-deploy.git
cd talqo-deploy/docker-compose
cp .env.example .envSet APP_SECRET and POSTGRES_PASSWORD in .env, following the comments there, then start the stack. Talqo runs its own migrations on start:
docker compose up -dThe dashboard is on http://127.0.0.1:3000. Everything is served from that one origin, so there is no CORS setup.
Exposing Talqo
The published port binds to loopback, so nothing outside the machine can reach Talqo until you put a reverse proxy in front of it. Talqo serves plain HTTP and does not terminate TLS itself.
Add a proxy such as Caddy or Traefik in the same Compose project, point it at the app service on port 3000, and give it a certificate. Serve Talqo at the domain root rather than a subfolder, because the widget script resolves absolute paths from the origin.
If your proxy runs on a separate machine or container network, add that network's address to TALQO_TRUSTED_PROXY_CIDRS so rate limiting sees real visitor addresses instead of the proxy's.
Talqo speaks HTTP/1.1, so your proxy handles TLS and can offer clients HTTP/2 or HTTP/3 on its own.
Chat replies stream over Server-Sent Events, so the proxy must not buffer responses and must allow reads longer than TALQO_CHAT_GENERATION_TIMEOUT_SECONDS. nginx breaks both by default: it withholds streamed replies until the model finishes, and its 60s read timeout cuts generations short before Talqo's 120s default.
Keeping your data
Talqo stores its database and uploaded files in the talqo_postgres-data and talqo_uploads volumes. Back both up. Avoid docker compose down -v, which deletes them.
Back up APP_SECRET too. It encrypts the provider credentials you enter under Dashboard → AI configuration, and it cannot be recovered from the database. If you lose it, you must re-enter those credentials.
Updating
docker compose pull
docker compose up -dDatabase migrations are not reversible. Each pull that brings a newer image can change the schema, so dump the database first, or pin TALQO_VERSION to a specific version to decide when that happens.
End-user chat policy
Each variable below is available in .env and passed to the API by the Compose file, so you can change any of them there. Uncomment the ones you want in .env.example and restart.
| Variable | Default | Purpose |
|---|---|---|
TALQO_CHAT_DAILY_MESSAGE_LIMIT | 100 | Accepted questions per agent and normalized client network per UTC day |
TALQO_CHAT_MAX_CONCURRENT_GENERATIONS_PER_IP | 2 | Active generations per agent and normalized client network |
TALQO_CHAT_MAX_INPUT_CHARACTERS | 400000 | Unicode code-point limit for the complete model input |
TALQO_CHAT_MAX_OUTPUT_TOKENS | 16384 | Provider output ceiling |
TALQO_CHAT_GENERATION_TIMEOUT_SECONDS | 120 | Model-call timeout in seconds, up to 300 |
TALQO_TRUSTED_PROXY_CIDRS | Empty | Comma-separated proxy networks whose forwarding metadata is trusted |
TALQO_RATE_LIMIT_IPV6_PREFIX_LENGTH | 64 | IPv6 network prefix used for allowance and concurrency identity |
The API rejects invalid values at startup. These controls apply per agent/network, not deployment-wide, and do not implement billing or token quotas.
Configure TALQO_TRUSTED_PROXY_CIDRS only for proxies that actually terminate client connections. With no trusted proxy CIDRs, Talqo uses the direct peer address and ignores forwarding headers. Native IPv6 clients share a /64 by default; this resists temporary-address churn but can make visitors on the same network share an allowance. A narrower grouping such as /128 reduces sharing and increases bypass risk.