Add Docusaurus docs with Playwright screenshots; build and publish to GitLab Pages in CI

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Jonas Leder 2026-11-16 20:32:39 +01:00
commit 2389b682e9
21 changed files with 12575 additions and 0 deletions

2
.gitignore vendored
View file

@ -2,3 +2,5 @@ node_modules
dist
.env
*.db
/pager
/public

View file

@ -2,6 +2,7 @@ stages:
- test
- build
- bundle
- pages
BackendUnitTests:
image: golang:1.27.4-alpine
@ -14,6 +15,21 @@ BackendUnitTests:
- go vet ./...
- go test ./...
BackendBinary:
# Static binary for the screenshot job (sqlite is pure Go).
image: golang:1.27.4-alpine
stage: test
needs: []
variables:
CGO_ENABLED: "0"
script:
- cd backend
- go build -o ../pager .
artifacts:
paths:
- pager
expire_in: 1 day
FrontendBuild:
image: node:24.22-alpine
stage: test
@ -26,6 +42,10 @@ FrontendBuild:
- cd frontend
- pnpm install --frozen-lockfile
- pnpm build # no unit tests yet
artifacts:
paths:
- frontend/dist
expire_in: 1 day
.docker:
image: jonasled.dev/infra/docker-build:master@sha256:d6f535fcb2817edec221eac33331369863f3409322d5f2d516356e7e7554326b
@ -86,3 +106,48 @@ HelmChart:
artifacts:
paths:
- dist/
Screenshots:
# Starts the real backend with the built UI on a fresh sqlite database, fills it with demo data and
# takes the screenshots used by the docs. They are regenerated on every pipeline run.
image: mcr.microsoft.com/playwright:v1.49.1-noble
stage: build
needs:
- BackendBinary
- FrontendBuild
variables:
NODE_OPTIONS: --experimental-sqlite # node:sqlite is used to backdate the demo alerts
before_script:
- npm install -g pnpm
script:
- DB_DRIVER=sqlite DB_NAME=/tmp/pager.db PORT=8080 JWT_SECRET=ci STATIC_DIR=frontend/dist ./pager > backend.log 2>&1 &
- for i in $(seq 30); do curl -sf localhost:8080/api/health && break; sleep 1; done
- cd docs
- pnpm install --frozen-lockfile
- SQLITE_FILE=/tmp/pager.db BASE=http://localhost:8080 pnpm screenshots
artifacts:
paths:
- docs/static/img/screenshots
expire_in: 1 week
when: always
pages:
# Docusaurus site on GitLab Pages, with the screenshots from this run. CI_PAGES_URL sets url and baseUrl.
image: node:24.22-alpine
stage: pages
needs:
- Screenshots
before_script:
- npx get-pnpm
- export PNPM_HOME='/root/.local/share/pnpm'
- export PATH="$PNPM_HOME/bin:$PATH"
script:
- cd docs
- pnpm install --frozen-lockfile
- pnpm build
- mv build ../public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

View file

@ -17,3 +17,6 @@ DB: `DB_DRIVER` = `postgres` | `mariadb` | `sqlite`, with single `DB_HOST/PORT/U
4. Alerts list shows open-since, refresh count and last refresh. Assign, ack, close, comment in UI or from the notification buttons.
Regenerate API docs after changing annotations: `cd backend && swag init --parseInternal -g main.go`
## Docs
Docusaurus site in `docs/` (`cd docs && pnpm install && pnpm start`). Screenshots are not committed: CI starts the real app, seeds demo data and takes them with Playwright (`pnpm screenshots`) on every run, then publishes the site to GitLab Pages from the default branch.

4
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,4 @@
node_modules
build
.docusaurus
static/img/screenshots

33
docs/docs/alerts.md Normal file
View file

@ -0,0 +1,33 @@
---
title: Working with alerts
---
import Screenshot from '@site/src/components/Screenshot'
## The list
The alert list refreshes itself every few seconds. For each alert it shows the priority, the status, **how long it has been open**, **how often it was refreshed** by the source and when the last refresh came in, and the assignee.
<Screenshot name="alerts" alt="Alert list" />
Tabs filter by *Active* (open and acknowledged), *Open*, *Acknowledged*, *Closed* and *All*. The search box looks into message and description. Quick buttons acknowledge or close without opening the alert.
## Statuses
| Status | Meaning |
| --- | --- |
| open | Firing, nobody has taken it |
| acknowledged | Someone is on it. Acknowledging an unassigned alert assigns it to you |
| closed | Resolved by the source or closed by a user |
If the same alert fires again after it was closed, a new alert is created.
## Detail view
<Screenshot name="alert-detail" alt="Alert detail with activity log" />
The detail view shows the description, the labels, when the alert was first seen, how often it was refreshed, the last refresh and a link back to Prometheus. Use the dropdown to **assign** it to a user; that user gets a push notification. Everything that happens is written to the **activity log**: creation, updates sent by Prometheus, comments, assignments, acknowledge and close.
## Priorities
Priorities are P1 (highest) to P5. From Alertmanager they come from the `priority` label; the default is P3. P1 and P2 push notifications stay on screen until dismissed.

13
docs/docs/api.md Normal file
View file

@ -0,0 +1,13 @@
---
title: API
---
The backend serves interactive API docs (Swagger UI) at `/swagger/index.html`. Run the backend locally to use it; the frontend container does not expose it.
All routes live under `/api`. Sign in with `POST /api/auth/login` (or register); the session is the `token` cookie. Routes under `/api/ingest/<token>/` are public and authenticated by the token in the URL.
Regenerate the spec after changing handler annotations:
```bash
cd backend && swag init --parseInternal -g main.go
```

30
docs/docs/deployment.md Normal file
View file

@ -0,0 +1,30 @@
---
title: Deployment
---
## Images
The CI builds two images: `backend` (the Go binary) and `frontend` (nginx with the UI, proxying `/api/` to a service named `backend`).
## Helm
CI pushes the chart to the project's OCI registry:
```bash
helm install pager oci://<registry>/<project-path>/charts/pager --version <version> \
--set secrets.inline.jwtSecret=$(openssl rand -hex 32) \
--set ingress.enabled=true --set 'ingress.hosts={pager.example.com}'
```
Important values:
| Value | Meaning |
| --- | --- |
| `config.database.driver` | `sqlite` (default, one backend replica, PVC at `/data`), `postgres` or `mariadb` |
| `config.database.host/port/name/user` | Connection entries for postgres and mariadb |
| `secrets.inline.jwtSecret`, `secrets.inline.dbPassword` | Or use `secrets.existingSecret` with keys `JWT_SECRET`, `DB_PASSWORD` |
| `secrets.inline.vapidPublicKey/vapidPrivateKey` | Optional; otherwise generated and stored in the database |
| `config.cookieSecure` | `true` by default. Set `false` only without HTTPS |
| `replicaCount` | Needs postgres or mariadb when above 1 |
The backend accepts traffic from the frontend pods only (network policy). Run one release per namespace because the service names are fixed. Terminate TLS at the ingress: Web Push needs HTTPS.

View file

@ -0,0 +1,35 @@
---
title: Getting started
---
import Screenshot from '@site/src/components/Screenshot'
## Run it
```bash
cd frontend && pnpm install && pnpm build
cd ../backend && cp .env.example .env && go run .
```
The backend serves the API, the built UI (`STATIC_DIR`) and the Swagger UI at `/swagger/index.html`.
### Database
Set `DB_DRIVER` to `postgres` (default), `mariadb` or `sqlite`, and the single entries `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` (and `DB_SSLMODE` for postgres). For sqlite, `DB_NAME` is the file path. Migrations run on start.
### Other settings
| Variable | Meaning |
| --- | --- |
| `PORT` | Listen port, default `8080` |
| `LOG_LEVEL` | `ERROR`, `WARN`, `INFO`, `DEBUG` |
| `JWT_SECRET` | Signs session cookies. If unset, a random one is used and sessions end on restart |
| `COOKIE_SECURE` | `true` to send the session cookie over HTTPS only |
| `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` | Web Push keys. If unset they are generated once and stored in the database |
| `VAPID_SUBJECT` | Contact for push services, e.g. `mailto:ops@example.com` |
## Register
Open the app and choose **Register**. This creates your organisation (tenant) and makes you its **owner**.
<Screenshot name="register" alt="Registration form" />

54
docs/docs/inbound.md Normal file
View file

@ -0,0 +1,54 @@
---
title: Inbound
---
The inbound URLs contain a secret tenant token. Owners and admins find them on the **Team** page and can rotate the token there. Rotating makes the old URLs stop working.
## Prometheus Alertmanager
```yaml
receivers:
- name: pager
webhook_configs:
- url: https://pager.example.com/api/ingest/<token>/alertmanager
send_resolved: true
```
Pager reads the status of every alert in the payload:
- **firing:** a new alert is created. If the same alert (Alertmanager fingerprint) is already open, it is *refreshed*: the refresh counter and the last-refresh time go up.
- **resolved:** the open alert is closed and the assignee is notified.
### Updating and commenting from Prometheus
As in Opsgenie, a refresh can change the alert. Pager maps:
| Source | Alert field |
| --- | --- |
| annotation `summary` (or `message`, else label `alertname`) | message |
| annotation `description` | description |
| label `priority` (`P1`–`P5`) | priority |
| annotation `comment` | adds a comment, only when the text changed |
Changes to message, description or priority show up in the activity log.
```yaml
- alert: HighCPU
expr: cpu > 0.9
labels:
priority: P2
annotations:
summary: CPU high on {{ $labels.instance }}
description: "{{ $value }} used"
comment: Runbook https://wiki.example.com/cpu
```
## Generic webhook
```bash
curl -X POST https://pager.example.com/api/ingest/<token>/webhook \
-H 'Content-Type: application/json' \
-d '{"alias":"backup-job","message":"Backup failed","description":"exit 2","priority":"P2","status":"firing","comment":"see log","labels":{"host":"db1"}}'
```
`alias` is the de-duplication key (default: `message`). `status` is `firing` (default) or `resolved`. Sending the same alias again refreshes the alert.

15
docs/docs/intro.md Normal file
View file

@ -0,0 +1,15 @@
---
slug: /
title: Pager
---
import Screenshot from '@site/src/components/Screenshot'
Pager is a small, self-hosted alerting tool in the spirit of Opsgenie.
- **Multi-tenant:** anyone can register, which creates a new tenant. Inside a tenant the owner adds users with roles.
- **Inbound:** Prometheus Alertmanager (new and resolved) and a generic webhook.
- **On-call UI as a PWA:** see what is open, since when, and how often Prometheus refreshed it. Install it on your phone and get push notifications with *Acknowledge* and *Close* buttons.
- **Triage:** assign alerts to users, acknowledge, close, reopen, comment.
<Screenshot name="alerts" alt="Alert list with open alerts" />

View file

@ -0,0 +1,25 @@
---
title: Push notifications and PWA
---
import Screenshot from '@site/src/components/Screenshot'
<Screenshot name="mobile-alerts" alt="Alert list on a phone" mobile />
The UI is a Progressive Web App. Install it from the browser menu (*Add to home screen* / *Install*).
## Turn on notifications
Click **Enable notifications** in the header and allow the permission. Each device subscribes on its own. Web Push needs HTTPS (or `localhost`).
## Who gets what
| Event | Receivers |
| --- | --- |
| New alert | All users of the tenant who enabled notifications |
| Assigned to you | You |
| Alert you are assigned to was resolved | You |
Notifications are titled `[P1] message`. One alert always uses one notification slot, so a newer update replaces the older one. New-alert notifications have **Acknowledge** and **Close** buttons that act on the alert without opening the app. Tapping the notification opens the alert.
Dead subscriptions (browser reports gone) are removed automatically.

17
docs/docs/team.md Normal file
View file

@ -0,0 +1,17 @@
---
title: Team and roles
---
import Screenshot from '@site/src/components/Screenshot'
<Screenshot name="team" alt="Team page" />
| Role | Can |
| --- | --- |
| owner | Everything. Created at registration, cannot be changed or removed |
| admin | Add, change and remove users, see and rotate the inbound token |
| member | Work with alerts |
Admins add users with a name, email and initial password, and can change a role, reset a password or remove a user. Removing a user unassigns their alerts and deletes their push subscriptions. Email addresses are unique across all tenants.
Every query is scoped to the tenant of the signed-in user, so tenants never see each other's alerts or users.

31
docs/docusaurus.config.js Normal file
View file

@ -0,0 +1,31 @@
// On GitLab Pages CI_PAGES_URL is the full site URL (maybe with a path), so the base URL needs no manual setting.
const pages = process.env.CI_PAGES_URL ? new URL(process.env.CI_PAGES_URL) : null
/** @type {import('@docusaurus/types').Config} */
module.exports = {
title: 'Pager',
tagline: 'Multi-tenant alerting with Alertmanager, on-call UI and push notifications',
url: pages ? pages.origin : 'http://localhost',
baseUrl: pages ? pages.pathname.replace(/\/?$/, '/') : '/',
favicon: 'img/icon.svg',
onBrokenLinks: 'throw',
markdown: { hooks: { onBrokenMarkdownLinks: 'throw' } },
presets: [
[
'classic',
{
docs: { routeBasePath: '/', sidebarPath: './sidebars.js' },
blog: false,
theme: { customCss: './src/custom.css' },
},
],
],
themeConfig: {
colorMode: { respectPrefersColorScheme: true },
navbar: {
title: 'Pager',
logo: { alt: 'Pager', src: 'img/icon.svg' },
},
footer: { style: 'dark', copyright: 'Pager documentation. Screenshots are regenerated on every pipeline run.' },
},
}

19
docs/package.json Normal file
View file

@ -0,0 +1,19 @@
{
"name": "pager-docs",
"private": true,
"version": "0.1.0",
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"screenshots": "node scripts/screenshots.mjs"
},
"dependencies": {
"@docusaurus/core": "3.10.2",
"@docusaurus/preset-classic": "3.10.2",
"react": "^18.3.1",
"react-dom": "^18.3.1"
},
"devDependencies": {
"playwright": "1.49.1"
}
}

12124
docs/pnpm-lock.yaml generated Normal file

File diff suppressed because it is too large Load diff

10
docs/pnpm-workspace.yaml Normal file
View file

@ -0,0 +1,10 @@
allowBuilds:
esbuild: true
core-js: true
core-js-pure: true
"@swc/core": true
onlyBuiltDependencies:
- esbuild
- core-js
- core-js-pure
- "@swc/core"

View file

@ -0,0 +1,81 @@
// Seeds a running Pager (BASE, default http://localhost:8080, fresh database) with demo data and takes the doc screenshots.
import { chromium } from 'playwright'
import { mkdirSync } from 'node:fs'
const BASE = process.env.BASE || 'http://localhost:8080'
const OUT = new URL('../static/img/screenshots/', import.meta.url).pathname
mkdirSync(OUT, { recursive: true })
const post = async (ctx, path, body) => {
const r = await ctx.request.post(BASE + '/api' + path, { data: body })
if (!r.ok()) throw new Error(`${path}: ${r.status()} ${await r.text()}`)
}
const browser = await chromium.launch()
const ctx = await browser.newContext({ viewport: { width: 1180, height: 760 }, baseURL: BASE })
const page = await ctx.newPage()
// Register through the UI
await page.goto('/register')
await page.fill('input[placeholder="Organisation name"]', 'Acme Ops')
await page.fill('input[placeholder="Your name"]', 'Ann Admin')
await page.fill('input[type=email]', 'ann@acme.example')
await page.fill('input[type=password]', 'correct-horse-battery')
await page.screenshot({ path: OUT + 'register.png' })
await page.click('button.primary')
await page.waitForSelector('text=Nothing here')
// Seed alerts through both inbound transports
const { token } = await (await ctx.request.get(BASE + '/api/tenant')).json()
const am = (name, prio, summary, desc, fp, extra = {}, status = 'firing') => fetch(`${BASE}/api/ingest/${token}/alertmanager`, {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ alerts: [{ status, fingerprint: fp, labels: { alertname: name, priority: prio, instance: 'web-1:9100', job: 'node' }, annotations: { summary, description: desc, ...extra }, generatorURL: 'http://prometheus.example/graph' }] }),
})
await am('HighCPU', 'P1', 'CPU above 90% on web-1', 'CPU usage is 91%', 'cpu1')
for (const v of [93, 95, 97, 97]) await am('HighCPU', 'P1', 'CPU above 90% on web-1', `CPU usage is ${v}%`, 'cpu1', { comment: 'Runbook: https://wiki.example/cpu' })
await am('DiskAlmostFull', 'P2', 'Disk /var 92% full on db-1', '/var has 8 GB left', 'disk1')
await am('DiskAlmostFull', 'P2', 'Disk /var 92% full on db-1', '/var has 7 GB left', 'disk1')
await am('CertExpiry', 'P4', 'Certificate expires in 10 days', 'api.acme.example', 'cert1')
await am('OldAlert', 'P3', 'Queue was backed up', 'resolved soon', 'q1')
await am('OldAlert', 'P3', 'Queue was backed up', 'resolved soon', 'q1', {}, 'resolved')
await fetch(`${BASE}/api/ingest/${token}/webhook`, {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ alias: 'nightly-backup', message: 'Nightly backup failed', description: 'exit code 2', priority: 'P3' }),
})
// Team and triage
await post(ctx, '/users', { name: 'Bob Builder', email: 'bob@acme.example', password: 'correct-horse-battery', role: 'admin' })
await post(ctx, '/users', { name: 'Cara Coder', email: 'cara@acme.example', password: 'correct-horse-battery', role: 'member' })
await post(ctx, '/alerts/1/assign', { user_id: 2 }) // HighCPU -> Bob
await post(ctx, '/alerts/1/comments', { text: 'Looking at it, a deploy is running.' })
await post(ctx, '/alerts/2/ack')
// Make the seeded alerts look lived-in (needs the sqlite file of the backend; skipped otherwise)
if (process.env.SQLITE_FILE) {
const { DatabaseSync } = await import('node:sqlite')
const db = new DatabaseSync(process.env.SQLITE_FILE)
const ago = (min) => new Date(Date.now() - min * 60000).toISOString()
const aged = { cpu1: [200, 2], disk1: [55, 9], cert1: [14 * 60, 14 * 60], 'wh-': [2 * 1440 + 300, 2 * 1440 + 300] }
for (const [fp, [first, last]] of Object.entries(aged))
db.prepare('UPDATE alerts SET first_seen_at = ?, last_seen_at = ? WHERE fingerprint LIKE ?').run(ago(first), ago(last), fp + '%')
db.exec('UPDATE alert_events SET created_at = (SELECT first_seen_at FROM alerts WHERE alerts.id = alert_events.alert_id)')
db.close()
}
const shot = async (p, name, wait) => {
await p.goto(name.path)
await p.waitForSelector(wait)
await p.waitForTimeout(300)
await p.screenshot({ path: OUT + name.file + '.png' })
}
await shot(page, { path: '/', file: 'alerts' }, '.row')
await shot(page, { path: '/alerts/1', file: 'alert-detail' }, '.timeline li')
await shot(page, { path: '/team', file: 'team' }, 'table')
// Phone view
const mctx = await browser.newContext({ viewport: { width: 390, height: 780 }, deviceScaleFactor: 2, storageState: await ctx.storageState(), baseURL: BASE })
const m = await mctx.newPage()
await shot(m, { path: '/', file: 'mobile-alerts' }, '.row')
await browser.close()
console.log('screenshots written to', OUT)

3
docs/sidebars.js Normal file
View file

@ -0,0 +1,3 @@
module.exports = {
docs: ['intro', 'getting-started', 'alerts', 'team', 'inbound', 'notifications', 'deployment', 'api'],
}

View file

@ -0,0 +1,7 @@
import React from 'react'
import useBaseUrl from '@docusaurus/useBaseUrl'
// Images in static/img/screenshots are generated by `pnpm screenshots` (CI does it on every run).
export default function Screenshot({ name, alt, mobile }) {
return <img className={'screenshot' + (mobile ? ' mobile' : '')} src={useBaseUrl(`/img/screenshots/${name}.png`)} alt={alt} loading="lazy" />
}

3
docs/src/custom.css Normal file
View file

@ -0,0 +1,3 @@
:root{--ifm-color-primary:#ea580c;--ifm-color-primary-dark:#d9500b;--ifm-color-primary-light:#f97316}
.screenshot{border:1px solid var(--ifm-color-emphasis-300);border-radius:10px;max-width:100%;margin:12px 0}
.screenshot.mobile{max-width:320px}

1
docs/static/img/icon.svg vendored Normal file
View file

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><rect width="512" height="512" fill="#0f172a"/><g fill="none" stroke="#f97316" stroke-width="34" stroke-linecap="round" stroke-linejoin="round"><path d="M168 340V250a88 88 0 0 1 176 0v90l28 28H140z"/><path d="M226 400a30 30 0 0 0 60 0"/></g></svg>

After

Width:  |  Height:  |  Size: 310 B