Deployment
Production deployment for CH-UI server + remote ClickHouse connectors
This guide covers the recommended production topology:
- VM2:
ch-ui server(web app/API/gateway) - VM1..N:
ch-ui connectnext to each ClickHouse instance
Topology
Browser
- SQL workspace
- Governance
- Brain UI
HTTPS
CH-UI Server
- :3488 API + UI
- Tunnel gateway
- Scheduler + syncers
WSS
Connector Host
- ch-ui connect
- Outbound only
SQLite
- Sessions, queries
- Governance, chats, audit
ClickHouse
- Your data
- HTTP :8123
Browser
- SQL workspace
- Governance
- Brain UI
HTTPS
CH-UI Server
- :3488 API + UI
- Tunnel gateway
- Scheduler + syncers
WSS
Connector Host
- ch-ui connect
- Outbound only
SQLite
- Sessions, queries
- Governance, chats, audit
ClickHouse
- Your data
- HTTP :8123
1) Start CH-UI Server (VM2)
Binary install:
ch-ui server --port 3488 --detach
ch-ui server statusDocker install (official image):
docker run -d \
--name ch-ui-server \
--restart unless-stopped \
-p 3488:3488 \
-v ch-ui-data:/app/data \
-e APP_URL=https://ch-ui.yourcompany.com \
-e APP_SECRET_KEY='replace-with-a-strong-secret' \
ghcr.io/caioricciuti/ch-ui:latest
curl http://localhost:3488/healthServer lifecycle:
ch-ui server start --detach
ch-ui server status
ch-ui server restart
ch-ui server stop2) Create Tunnel Connection + Token (VM2)
Use CLI on the server host (the machine where ch-ui.db lives):
ch-ui tunnel create --name "vm1-clickhouse" --url wss://your-ch-ui-domain/connect
ch-ui tunnel list
ch-ui tunnel show <connection-id>If the server runs in Docker, run tunnel commands through the container:
docker exec -it ch-ui-server ch-ui tunnel create --name "vm1-clickhouse" --url wss://your-ch-ui-domain/connect
docker exec -it ch-ui-server ch-ui tunnel show <connection-id>Copy the generated token (cht_...).
Optional UI path (Pro/Admin): create/manage additional connections in Admin.
3) Start Connector (VM1)
ch-ui connect \
--url wss://your-ch-ui-domain/connect \
--key cht_your_token \
--clickhouse-url http://127.0.0.1:8123If a stale session exists:
ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_token --takeover4) Run Connector As Service
ch-ui service install \
--url wss://your-ch-ui-domain/connect \
--key cht_your_token \
--clickhouse-url http://127.0.0.1:8123
ch-ui service status
ch-ui service start5) Reverse Proxy (Nginx)
Basic TLS proxy for UI/API and WebSocket tunnel:
server {
listen 443 ssl http2;
server_name ch-ui.yourcompany.com;
location / {
proxy_pass http://127.0.0.1:3488;
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;
}
location /connect {
proxy_pass http://127.0.0.1:3488/connect;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600;
}
}6) Hardening Checklist
- Set strong
APP_SECRET_KEY. - Set
APP_URLto public HTTPS URL. - Restrict
ALLOWED_ORIGINS. - Keep
database_pathon persistent disk. - Run daily backups of
ch-ui.db. - Enable service supervision for
serverandconnect.
Backup and Restore
CH-UI state is stored in SQLite (database_path), so backup is simple:
cp /var/lib/ch-ui/ch-ui.db /var/backups/ch-ui-$(date +%F).dbRestore by replacing the DB file while the server is stopped.
Troubleshooting
Address already in use
status says port in use but no PID: stop the legacy process once, then restart using the current binary.
ch-ui server status
ch-ui server stopConnector invalid token
- Regenerate token with
ch-ui tunnel rotate <id>(or via Admin if Pro-enabled). - Restart connector with the new token.
Connector timeouts behind proxy
- Validate
/connectproxy upgrade headers (Upgrade,Connection: upgrade). - Set long read/send timeouts (e.g.
proxy_read_timeout 3600). - Check firewall egress from the connector host.
Health check
curl http://localhost:3488/health