chmonitorchmonitor
Deployment

One-Click Deploy Templates

Deploy chmonitor to Railway, Render, or Fly.io in minutes using community-maintained templates.

Deploy on Railway, Render, or Fly.io with community-maintained templates. Each runs the published image and wires a health check.

Starting-point templates, not verified pipelines

These are starting-point templates, not verified CI pipelines. They have not been boot-tested end-to-end against a live ClickHouse instance in automated CI. Review env placeholders, substitute real values, and verify before production.

Loading diagram…

Prerequisites

All three templates use ghcr.io/chmonitor/chmonitor:0.3, expose port 3000, and health-check /api/healthz. You must supply:

VariableDescription
CLICKHOUSE_HOSTClickHouse HTTP URL, e.g. http://your-host:8123
CLICKHOUSE_USERClickHouse username
CLICKHOUSE_PASSWORDClickHouse password (platform secret store)

Templates live in deploy/templates/.

railway.json
render.yaml
fly.toml

Setup

Template: deploy/templates/railway.json

Create a new project

In the Railway dashboard, choose New Project → Deploy from image and set the image to ghcr.io/chmonitor/chmonitor:0.3.

Set environment variables

Go to Variables and add the three env vars above. Use Railway's secret management for CLICKHOUSE_PASSWORD.

Open your app

Railway auto-assigns a public URL. Health check path: /api/healthz.

Alternatively, copy deploy/templates/railway.json into the repo root as railway.json.

{
  "build": {
    "builder": "IMAGE",
    "image": "ghcr.io/chmonitor/chmonitor:0.3"
  },
  "deploy": {
    "healthcheckPath": "/api/healthz"
  }
}

Template: deploy/templates/render.yaml

Fork or copy the template

Copy deploy/templates/render.yaml as render.yaml in the repository root.

Create a Blueprint

In Render: New → Blueprint and point it at your repository.

Set the password as a secret

Render pulls ghcr.io/chmonitor/chmonitor:0.3. Set CLICKHOUSE_PASSWORD as a Secret (do not leave it in render.yaml).

services:
  - type: web
    name: chmonitor
    image: ghcr.io/chmonitor/chmonitor:0.3
    healthCheckPath: /api/healthz
    envVars:
      - key: CLICKHOUSE_HOST
        value: http://YOUR_CLICKHOUSE_HOST:8123
      - key: CLICKHOUSE_USER
        value: YOUR_CLICKHOUSE_USER
      - key: CLICKHOUSE_PASSWORD
        value: YOUR_CLICKHOUSE_PASSWORD   # use Render secret instead

Template: deploy/templates/fly.toml

Install Fly CLI and login

fly auth login

Copy and edit the template

Copy deploy/templates/fly.toml. Edit app, primary_region, and CLICKHOUSE_HOST / CLICKHOUSE_USER.

Store the password as a secret

fly secrets set CLICKHOUSE_PASSWORD=your-password

Deploy

fly launch --no-deploy   # imports fly.toml
fly deploy

Health check polls /api/healthz every 10 seconds with a 20-second startup grace.

Verify

  • Open https://your-app-url — overview should load.
  • Empty charts → ClickHouse user needs SELECT on system.*.
  • Health check fails → CLICKHOUSE_HOST must be reachable from the container (private hostname, not localhost).

Troubleshooting

More configuration

Auth, AI agent, conversation store: same env vars as Docker.

Docker deployment

Full env var reference — auth, AI agent, and conversation store apply the same way.

Cloudflare Workers

Serverless, global hosting for the current v0.3+ app.

Kubernetes deployment

Install chmonitor with the Helm chart.

Production checklist

Harden and validate before exposing to a team or the internet.

Traefik

Put chmonitor behind Traefik as a reverse proxy on Kubernetes or Docker, with optional ForwardAuth for SSO via oauth2-proxy.

Production Checklist

Steps to harden and validate a chmonitor deployment before exposing it to a team or the internet.

On this page

PrerequisitesSetupCreate a new projectSet environment variablesOpen your appFork or copy the templateCreate a BlueprintSet the password as a secretInstall Fly CLI and loginCopy and edit the templateStore the password as a secretDeployVerifyTroubleshootingRelated