Services and Routing
This page covers what the Kanera stack runs, which parts to expose, and how to put a reverse proxy in front of them.
Read it after Getting Started has a deployment running, or before you start if you want to plan domains first.
Deployment shape
The standard compose file runs these services:
| Service | Purpose |
|---|---|
postgres | PostgreSQL database with persistent data in kanera_pgdata. |
valkey | Required Valkey instance for realtime fanout, presence, and shared rate limits. |
migrate | One-shot database migration service that runs before app services start. |
api | Main Kanera API and realtime server. |
worker | Single background worker for schedulers, webhook delivery, notifications, cleanup, and realtime outbox fallback. |
public-api | Public integration API. |
mcp | MCP Streamable HTTP server backed by the public API. |
web | Built Kanera web app served by nginx. |
db-backup | Optional encrypted PostgreSQL backup scheduler. |
The browser should connect to the web service. Do not expose the main api service directly; the web nginx container proxies app API and Socket.IO traffic internally.
Expose public-api only if you want external integrations. Expose mcp only if you want remote MCP clients to connect over HTTP.
Recommended domains
Use separate domains for the app, public API, and MCP when you expose all three:
| Domain | Service | Use |
|---|---|---|
kanera.example.com | web | The Kanera web app. |
api.kanera.example.com | public-api | REST API, webhooks, and API reference. |
mcp.kanera.example.com | mcp | Remote MCP endpoint for AI clients. |
The public API and MCP domains are optional. You can start with only the web app and add the others later.
Publish ports
The default compose file keeps services private. If you are running Docker directly on a server, add a compose.override.yml file:
services:
web:
ports:
- "8080:80"
public-api:
ports:
- "3001:3001"
mcp:
ports:
- "3002:3002"
Then point your HTTPS reverse proxy at:
| Public URL | Upstream |
|---|---|
https://kanera.example.com | http://127.0.0.1:8080 |
https://api.kanera.example.com | http://127.0.0.1:3001 |
https://mcp.kanera.example.com | http://127.0.0.1:3002 |
Only publish public-api and mcp when you need them.
Trust proxy settings
Set these when Kanera is behind a trusted reverse proxy such as nginx, Traefik, Dokploy, or an ingress that sends the real client IP:
API_TRUST_PROXY=true
PUBLIC_API_TRUST_PROXY=true
API_TRUST_PROXY helps app authentication rate limits use the real client IP. PUBLIC_API_TRUST_PROXY does the same for public API rate limits.
Leave them false only when the service is directly internet-facing or directly Cloudflare-facing.