Migrating from the ADR viewer

This page is for operators who ran the previous ADR_VIEWER_ service and are moving to Adriano. There is no automatic converter. Write a new catalog file by hand and validate it with the check-config command before pointing production traffic at it.

What changed for clients

The most significant change is that Adriano never reads a source while answering a request. The old service scraped its source on every /adr/ request. Adriano serves everything from its own index; only a poll or a CI push talks to a source.

GET /

The old service redirected to /docs. Adriano serves the web interface at / and has no redirect.

GET /adr/

Returned HTML, or JSON when asked for with an Accept header or ?json=true. Replaced by GET /api/v1/records (search and list) and GET /api/v1/records/{id} (detail). Both return JSON only; the web interface renders the HTML.

GET /healthz

Unchanged path, still public. The answer now reports each subsystem; see Health checks and logs.

GET /docs

Moved to GET /api/docs. The schema is at GET /openapi.json. Both are public and contain no records.

Settings

The old service configured one source through ADR_VIEWER_* environment variables. Adriano reads any number of named sources from catalog.yaml (located by ADRIANO_CONFIG_FILE) and uses ADRIANO_ environment variables for everything else. No variable maps one-to-one, but everything the old ones carried has a new home.

Which repository or path to scrape

A sources entry in the catalog file. See Connecting sources.

Source credentials

The token_env field of that entry names an environment variable that holds the token. The token itself is never written to the catalog file.

Which branch counts as authoritative

published_ref on the source entry: a branch name, or "@project-default" for GitLab.

SSO audience (adr_viewer)

ADRIANO_OIDC_AUDIENCE. The default is the same value, adr_viewer, so an existing identity-provider client registration keeps working unchanged.

Roles file (admin role grants read)

rbac.roles in the catalog file, for example admin: [read, operate]. Adriano adds the separate operate permission (starting polls) and a reviewer grant (approval_policy.reviewers). The old service had no approval workflow.

Development sign-in fixture

ADRIANO_DEV_AUTH_ENABLED and ADRIANO_DEV_SHARED_SECRET. Never enable these in production; see Authentication and access.

Container workers

ADRIANO_WORKERS. The old image started five worker processes; Adriano defaults to four. Raise it if your traffic needs more; each worker needs memory and database connections of its own.