cropalato/promview repository overview

⁠Promview

Operational console for alerts delivered by Prometheus Alertmanager. Promview ingests authenticated webhooks from multiple Alertmanager installations, keeps current alert state in PostgreSQL, and serves a live React console over REST and resumable server-sent events. Alertmanager stays responsible for routing, grouping, inhibition and notification.

• Source: https://github.com/cropalato/promview⁠
• Documentation: https://github.com/cropalato/promview/tree/main/docs⁠
• License: MIT

⁠Status

Promview is beta. Every feature on its first-release list is implemented and the committed scale is measured, but it has not been run in anger by anyone but its author. The API and schema are settled enough to build on; pin an exact tag rather than tracking a moving one in production.

⁠Tags and architecture

Images are built for linux/amd64 only. There is no arm64 image: the project publishes the one architecture it tests on rather than an emulated build nobody exercises.

⁠Requirements

Promview needs an externally managed PostgreSQL database. It neither bundles nor manages one, in any deployment.

⁠Quick start

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: promview
      POSTGRES_USER: promview
      POSTGRES_PASSWORD: promview
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U promview -d promview"]
      interval: 2s
      timeout: 3s
      retries: 15
    volumes:
      - postgres-data:/var/lib/postgresql/data

  migrate:
    image: cropalato/promview:beta
    command: ["migrate"]
    depends_on:
      postgres:
        condition: service_healthy
    environment: &app-environment
      PROMVIEW_DATABASE_URL: postgres://promview:promview@postgres:5432/promview?sslmode=disable
      PROMVIEW_BOOTSTRAP_SOURCE_SLUG: demo
      PROMVIEW_BOOTSTRAP_SOURCE_NAME: Development Alertmanager
      PROMVIEW_BOOTSTRAP_SOURCE_TOKEN: development-token

  app:
    image: cropalato/promview:beta
    depends_on:
      migrate:
        condition: service_completed_successfully
    environment: *app-environment
    ports:
      - "8080:8080"

volumes:
  postgres-data:

docker compose up -d

Open http://localhost:8080⁠. This stack runs in open mode: anonymous read-only, with ingestion still authenticated.

Migrations are a separate migrate command rather than something the server does on start, so two replicas cannot race the schema. Run it to completion before the application starts, on every upgrade.

Send an Alertmanager-compatible webhook to the bootstrapped demo source:

curl -X POST http://localhost:8080/api/v1/ingest/alertmanager/demo \
  -H 'Authorization: Bearer development-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "4",
    "alerts": [{
      "status": "firing",
      "labels": {"alertname": "ExampleAlert", "severity": "warning"},
      "annotations": {"summary": "Example alert delivery"},
      "startsAt": "2026-08-14T12:00:00Z"
    }]
  }'

Each source carries its own opaque bearer token, stored only as a SHA-256 hash. Provision or rotate one with the CLI in the same image:

docker compose run --rm app source set \
  --slug production \
  --name 'Production Alertmanager' \
  --token 'replace-with-at-least-16-characters'

⁠Ports

⁠Configuration

All configuration is environment variables. The container runs as UID/GID 65532 and holds no state on disk.

⁠Required

⁠Server

⁠Source bootstrap

Set the slug and the token together, or neither. Bootstrap initializes a source that is absent or has no credential; it never overwrites a token rotated with promview source set.

⁠Alert lifecycle

⁠OIDC

Required when PROMVIEW_AUTH_MODE=oidc. Promview uses discovery and Authorization Code with PKCE, keeps provider tokens server-side, and never trusts provider role claims directly: groups map to roles through server-owned bindings.

See docs/okta-oidc.md⁠ for a worked provider setup.

⁠Kubernetes

A Helm chart is published beside the image and runs this exact image as a serialized pre-install and pre-upgrade migration hook:

helm upgrade --install promview oci://ghcr.io/cropalato/charts/promview \
  --namespace promview \
  --create-namespace \
  --version 0.1.0-beta.3

The chart version is the application version. Create the PostgreSQL Secret before installing. See docs/kubernetes.md⁠.

⁠Also published at

docker pull ghcr.io/cropalato/promview:beta

⁠Desktop client

The same console ships as a Tauri desktop and tray client for Linux and Windows. Installers are attached to each GitHub release⁠.