Deployment

This guide covers the recommended production topology:

VM2: ch-ui server
VM1..N: ch-ui connect next to each ClickHouse instance

Topology

flowchart LR
    B[Browser] --> S[CH-UI Server :3488]
    S --> DB[(SQLite state)]
    A[ch-ui connect agent] <--> S
    A --> CH[ClickHouse HTTP :8123]

1) Start CH-UI Server (VM2)

./ch-ui server --port 3488 --detach
./ch-ui server status

Server lifecycle:

./ch-ui server start --detach
./ch-ui server status
./ch-ui server restart
./ch-ui server stop

2) Add Connection In UI

In CH-UI:

Go to Admin -> Connections.
Create a connection.
Copy the generated tunnel token (cht_...).

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:8123

If a stale session exists:

./ch-ui connect --url wss://your-ch-ui-domain/connect --key cht_your_token --takeover

4) 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 start

5) 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_URL to public HTTPS URL.
Restrict ALLOWED_ORIGINS.
Keep database_path on persistent disk.
Run daily backups of ch-ui.db.
Enable service supervision for server and connect.

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).db

Restore 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 stop

Connector `invalid token`

Regenerate token in Admin or via ch-ui tunnel rotate <id>.
Restart connector with the new token.

Connector timeouts behind proxy

Validate /connect proxy 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

Deployment

On this page