A role-aware IT service launcher for universities. Staff, teachers, and students each land on a dashboard pre-arranged for their kind of work — they can search the full service catalog, pin favorites, and stay informed through announcements. Admins curate the catalog and default views through a form UI or an MCP server.

Built as a Go modular monolith with an embedded React/TypeScript SPA, PostgreSQL, and generic OIDC authentication. Designed to be reused: all branding, OIDC claim mapping, and the product name are runtime config — no institution is hardcoded.

The primary dev loop runs without Docker. You'll need Go 1.26+, Node 24+, and Podman (or Docker — just swap podman for docker in the Makefile).

# 1. Copy the environment template and fill in any secrets
cp .env.example .env

# 2. Start a local Postgres 17 container
make db

# 3. Start the mock OIDC identity provider (needed for login)
make idp

# 4. Apply all migrations
make migrate

# 5. (Optional) seed the catalog with example services
make seed

# 6. Install frontend dependencies
make web-install

Then run the Go server and the Vite dev server in two separate terminals:

# Terminal A — Go API on :8080
make run

# Terminal B — Vite on :5173, proxying /api/* to :8080
make web-dev

Open http://localhost:5173 in your browser. The mock IdP lets you log in with any username; set is_admin: true in dev/mock-oidc-config.json to test admin features.

Note: after any schema change (migrations/ gets a new file), run make migrate before restarting the server.

make test         Run Go tests with the race detector
make lint         Run golangci-lint
make web-check    Frontend typecheck + lint + tests
make check        Run the full local gate (Go + frontend combined)
make migrate-down Roll back the last migration
make sqlc         Regenerate type-safe queries from SQL (after editing *.sql)
make build        Build a single binary with the SPA embedded → bin/server
make mcp          Build the admin MCP server → bin/mcp
make clean        Remove build artifacts

The Dockerfile builds the SPA (Node) and embeds it — along with the SQL migrations — into a static Go binary, producing one small distroless image (~20 MB) that runs as a non-root user with a read-only root filesystem. On every push to main (and every v* tag) CI publishes it to GHCR at ghcr.io/<owner>/<repo>.

The app applies forward-only migrations itself on startup (advisory-locked via goose, so rolling-deploy replicas don't race; a no-op when the schema is already current). There's no separate migration image or step — set AUTO_MIGRATE=false to opt out and run the goose CLI yourself.

Two compose files ship: compose.yaml builds from source (staging / a quick end-to-end run), and compose.prod.yaml pulls the released image (production). Both put Caddy in front as the only exposed surface, keep Postgres on an internal-only network, and harden every service (no-new-privileges, cap_drop: ALL, read-only roots). Caddy waits on the app's /readyz healthcheck before accepting traffic.

No source tree or build toolchain on the host. Point it at the published image and a released version, then bring it up:

export IMAGE_REPO=ghcr.io/<owner>/<repo>     # e.g. ghcr.io/virtuos/wolke
export WOLKE_VERSION=1.4.0                    # a released tag, or a @sha256 digest
docker compose -f compose.prod.yaml up -d     # or: podman-compose -f compose.prod.yaml up -d

On startup the app waits for Postgres, applies any pending migrations, then serves.

Everything fails closed — these must be set (in a .env beside the file, or the environment) or compose up aborts: IMAGE_REPO, WOLKE_VERSION, POSTGRES_PASSWORD, SESSION_SECRET, PUBLIC_URL, OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET. Before the first deploy, put the real hostname in the Caddyfile (replace localhost) and provide a config.yaml next to the compose file.

POSTGRES_PASSWORD=$(openssl rand -base64 24) SESSION_SECRET=$(openssl rand -base64 32) \
  docker compose up -d --build

Caddy serves HTTPS on :443 (its internal CA for localhost; real certificates for a public hostname). Rootless podman can't bind <1024 — set CADDY_HTTPS_PORT=8443 then. Bring up the mock IdP for a full login flow with --profile idp.

Branding and OIDC claim mapping live in config.yaml (copy from config.example.yaml). This is the one file you edit to reskin for a different institution — colors, logo paths, product name, and which OIDC claim maps to which role. OIDC is provider-agnostic (Keycloak, Authentik, Zitadel, Entra, …); for a step-by-step Keycloak setup see docs/oidc-keycloak.md. TRUSTED_PROXIES must cover the proxy's network so X-Forwarded-For is trusted (it's preset to the compose edge subnet).

Migrations are forward-only (goose) and applied by the app on startup (see above). Rolling back requires an explicit make migrate-down in dev.

The app exposes Prometheus metrics at GET /metrics on its own listener (:8080), in the standard Prometheus text format. The endpoint is mounted only when the metrics collector is wired (the default for the server binary).

All series are prefixed wolke_ (never an institution name), and labels are aggregate only — never a user identifier:

The histogram and click counter update in-process per request; the three gauges are refreshed from the database every 30s by a background worker. Metrics live on a private registry, so the endpoint exposes only these series — no default Go/process collectors.

Prometheus scrapes the app directly on the internal network (e.g. app:8080/metrics inside the Compose/cluster network); Grafana visualises it (a starter dashboard lives in deploy/grafana/).

/metrics must never be publicly reachable — and protection is by topology, not the application:

1. Caddy 404s it at the edge. The public vhost returns 404 for /metrics (see Caddyfile), so it is invisible from the internet.
2. The app port is internal-only. :8080 is not published to the host; only Caddy and Prometheus reach it, over the internal network.

In this setup you do not need an application-level secret — protecting at the reverse proxy + network boundary is the intended model. So METRICS_TOKEN is optional:

• Unset (default): /metrics serves with no auth. Correct when the scrape path stays inside a trusted network.
• Set: the endpoint additionally requires Authorization: Bearer <token> (constant-time compared). Reach for this only when the scrape path crosses a boundary you don't fully control — a shared/multi-tenant network, or cross-host scraping without mTLS.

The load-bearing invariant is that the app's :8080 isn't reachable by untrusted parties. The Caddy 404 only covers the public vhost — it does not protect a direct hit on the app port. So if you ever publish :8080 to the host or a shared LAN, set METRICS_TOKEN (or put mTLS in front of the scrape).

All admin endpoints require an authenticated session (login via OIDC) belonging to an admin user. Regular catalog reads are available to any authenticated user.

Writes happen immediately — no staging step. Every write is audit-logged with actor_kind = "form".

Services

Service body (create/update):

{
  "name": "VPN",
  "description": {
    "de": "Sicherer Zugang zum Hochschulnetz.",
    "en": "Secure access to the university network."
  },
  "service_url": "https://vpn.example.edu",
  "doc_url": "https://docs.example.edu/vpn",
  "icon": "shield",
  "categories": ["netzwerk"],
  "tag": "wartung"
}

tag is optional — "beta" shows a blue badge, "wartung" shows an amber badge on the tile. Omit or set to "" for no badge.

Categories, announcements, role defaults

The MCP server gives Claude (or any MCP client) access to the same admin operations as the HTTP API, with one important difference: writes are staged. A propose_* call validates the change and returns a preview — no data is written. Only change.confirm with the returned token actually commits. Tokens expire after 10 minutes and are single-use.

Every confirmed write is audit-logged with actor_kind = "mcp", distinct from form writes.

The admin user must have logged into the web UI at least once so their record exists in the database.

make mcp   # builds bin/mcp

Set these environment variables when launching the binary:

DATABASE_URL    postgres connection string (same as the app)
MCP_ADMIN_SUB   OIDC subject of the admin user (find it in the audit log or DB)
CONFIG_FILE     optional path to config.yaml

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "wolke-admin": {
      "command": "/path/to/bin/mcp",
      "env": {
        "DATABASE_URL": "postgres://wolke:…@localhost:5432/wolke?sslmode=disable",
        "MCP_ADMIN_SUB": "the-admin-oidc-sub"
      }
    }
  }
}

Reads (no staging required):

Propose (validates and stages — no write, returns a change_token and before/after preview):

Commit or discard:

A second, read-only MCP server that any university member can run — no admin rights, no user identity required. It exposes the same public catalog the web UI shows: which services exist, which are in maintenance or beta, where their documentation lives, plus search and active announcements. It has no write path at all (enforced at the package level), and never returns soft-deleted services.

It needs only a database connection — set DATABASE_URL.

make catalog-mcp   # builds bin/catalog-mcp

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "wolke-catalog": {
      "command": "/path/to/bin/catalog-mcp",
      "env": {
        "DATABASE_URL": "postgres://wolke:…@localhost:5432/wolke?sslmode=disable"
      }
    }
  }
}

For defense-in-depth, point DATABASE_URL at a Postgres role with only SELECT grants — the server only ever reads.

Apache 2.0