chmonitor
Deployment

Traefik

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

Run chmonitor behind Traefik as your reverse proxy / ingress controller. Works the same on Kubernetes (IngressRoute CRD or the standard Ingress) and with plain Docker (container labels).

Traefik handles TLS, routing, and — combined with oauth2-proxy — authentication, so chmonitor itself can stay on the none provider and trust the forwarded identity.

Prerequisites

What you need

  • A running Traefik instance (ingress controller on Kubernetes, or Docker provider watching your containers)
  • chmonitor deployed via the Helm chart or Docker
  • For SSO: an oauth2-proxy instance (Dex, Google, GitHub, …)

Setup

Pick your platform. chmonitor listens on port 3000 in every case.

If you installed chmonitor with the Helm chart, expose the Service with a Traefik IngressRoute:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: chmonitor
  namespace: monitoring
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`chmonitor.example.com`)
      kind: Rule
      services:
        - name: chmonitor          # matches the chart's Service name
          port: 3000               # service.port (default 3000)
  tls:
    certResolver: letsencrypt      # or a cert-manager-issued Secret via tls.secretName

Prefer the standard Ingress? Enable it in the chart and point the class at Traefik:

ingress:
  enabled: true
  className: traefik
  hosts:
    - host: chmonitor.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts: [chmonitor.example.com]
      secretName: chmonitor-tls

With docker compose and Traefik watching the Docker provider:

services:
  chmonitor:
    image: ghcr.io/chmonitor/chmonitor:latest
    environment:
      CLICKHOUSE_HOST: http://clickhouse:8123
      CLICKHOUSE_USER: default
      CLICKHOUSE_PASSWORD: ""
    labels:
      - traefik.enable=true
      - traefik.http.routers.chmonitor.rule=Host(`chmonitor.example.com`)
      - traefik.http.routers.chmonitor.entrypoints=websecure
      - traefik.http.routers.chmonitor.tls.certresolver=letsencrypt
      - traefik.http.services.chmonitor.loadbalancer.server.port=3000

Authentication via ForwardAuth

Put chmonitor behind oauth2-proxy (with Dex, Google, GitHub, …) using a Traefik ForwardAuth middleware, and have chmonitor read the forwarded identity with the trusted auth provider.

Define the ForwardAuth middleware

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth2-proxy-auth
  namespace: monitoring
spec:
  forwardAuth:
    address: http://oauth2-proxy.monitoring.svc.cluster.local/oauth2/auth
    trustForwardHeader: true
    # Copy oauth2-proxy's identity headers back onto the upstream request.
    authResponseHeaders:
      - X-Auth-Request-User
      - X-Auth-Request-Email
      - X-Auth-Request-Preferred-Username
      - X-Auth-Request-Groups

Attach the middleware to the route

Add middlewares: [{ name: oauth2-proxy-auth }] on the IngressRoute, or traefik.http.routers.chmonitor.middlewares=... on Docker.

Configure chmonitor's trusted provider

CHM_AUTH_PROVIDER=trusted
# oauth2-proxy forwards X-Auth-Request-* (not X-Forwarded-*) through ForwardAuth
CHM_TRUSTED_USER_HEADER=X-Auth-Request-User
CHM_TRUSTED_EMAIL_HEADER=X-Auth-Request-Email
CHM_TRUSTED_NAME_HEADER=X-Auth-Request-Preferred-Username
CHM_TRUSTED_GROUPS_HEADER=X-Auth-Request-Groups
# Restrict to specific Dex groups (optional)
CHM_TRUSTED_ALLOWED_GROUPS=sre,platform-admins

See Trusted proxy for the full header reference, the shared-secret vs CHM_TRUSTED_ALLOW_INSECURE tradeoff, and the Dex/oauth2-proxy flags.

Verify

chmonitor exposes /healthz (liveness, static) and /api/healthz (readiness, gated on ClickHouse). Traefik can health-check the service:

# IngressRoute service entry
services:
  - name: chmonitor
    port: 3000
    healthCheck:
      path: /healthz
      intervalSeconds: 15

Don't guard health endpoints with ForwardAuth

Make sure your ForwardAuth middleware does not guard /healthz and /api/healthz, or probes will be redirected to the login flow. Route those paths without the auth middleware (a separate, higher-priority router rule), or rely on the chart's Kubernetes probes which hit the pod directly and bypass Traefik.

Troubleshooting

Probes redirected to login

If health probes fail after enabling ForwardAuth, the middleware is likely guarding /healthz / /api/healthz. Route those paths without the auth middleware, or lean on the chart's Kubernetes probes that hit the pod directly.

Kubernetes deployment

Install chmonitor with the Helm chart.

Docker deployment

Run the published container behind Traefik's Docker provider.

Trusted proxy authentication

Header reference, shared-secret tradeoff, and Dex/oauth2-proxy flags.

Authentication overview

Choose an auth provider for chmonitor.

Production checklist

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

Self-host (Node / standalone)

Run chmonitor on any server using Node.js or Bun — bare VMs, dedicated servers, or any environment where you manage the process directly.

One-Click Deploy Templates

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

On this page

PrerequisitesSetupAuthentication via ForwardAuthDefine the ForwardAuth middlewareAttach the middleware to the routeConfigure chmonitor's trusted providerVerifyTroubleshootingRelated