# Traefik

Run chmonitor behind [Traefik](https://traefik.io/) 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/trusted-proxy) — authentication, so chmonitor itself can stay on the `none` provider and trust the forwarded identity.

## Kubernetes (IngressRoute)

If you installed chmonitor with the [Helm chart](/deploy/k8s), expose the Service with a Traefik `IngressRoute`:

```yaml
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:

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

## Docker (labels)

With `docker compose` and Traefik watching the Docker provider:

```yaml
services:
  chmonitor:
    image: ghcr.io/duyet/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](/authentication/trusted-proxy).

```yaml
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 (`middlewares: [{ name: oauth2-proxy-auth }]` on the IngressRoute, or
`traefik.http.routers.chmonitor.middlewares=...` on Docker), then configure chmonitor:

```bash
CHM_AUTH_PROVIDER=trusted
VITE_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](/authentication/trusted-proxy) for the full header reference, the shared-secret vs `CHM_TRUSTED_ALLOW_INSECURE` tradeoff, and the Dex/oauth2-proxy flags.

## Health checks

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

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

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.

## Related

- [Kubernetes deployment](/deploy/k8s)
- [Docker deployment](/deploy/docker)
- [Trusted proxy authentication](/authentication/trusted-proxy)
- [Authentication overview](/authentication)
- [Production checklist](/deploy/production-checklist)