Skip to content

ADR-005: Deployment Architecture — Plugins and Database

Audience: host — see ADR index.

Status: Proposed Date: 2026-04-09 Deciders: Portal team

Context

Admin functionality (wizard, admin pages, config API, auth modes) must be added to the portal's plugin ecosystem. The question is whether to create new packages or extend existing ones. Separately, the RHEL VM needs a database — the question is whether to require external PostgreSQL or bundle it.

Alternatives Considered

Plugin packaging

Alternative Source Why rejected
Three new packages (admin-frontend, admin-backend, admin-common) — Duplicated build/packaging infra; extra artifacts to publish and version; shared state complexity

Database provisioning (RHEL VM)

Alternative Source Why rejected
External DB required on VM — Highest install friction; 8/14 competitors bundle a database; Day-0 complexity discourages adoption
SQLite for production — No concurrent writes; no built-in auth; dev-only per upstream Backstage guidance

Decision

1. Prefer existing packages; backend ownership remains proposed.

The existing @ansible/plugin-backstage-rhaap package is a frontend plugin. It cannot own the proposed server-side config store, setup API, or restart service. The backend target is not selected by this ADR; the implementation proposal must name a backend plugin/module and its dependencies before work begins. If that requires a new package or package split, record that change rather than assigning server responsibilities to the frontend package.

Functionality Target Package
Config DB, setup API, restart, CLI Backend owner to be selected in the implementation proposal
Admin pages, wizard UI Host frontend owner to be confirmed; preserve administration when portal-scaffolder is omitted
Auth modes auth-backend-module-rhaap-provider
Shared types backstage-rhaap-common

Admin pages lazy-loaded via React.lazy() — non-admin users never download admin code.

2. Bundled PostgreSQL on RHEL VM. Ships PostgreSQL via Podman container with auto-generated credentials (Podman secrets). External DB supported but not required. The portal Quadlet uses Requires=postgres.service and After=postgres.service so systemd starts PostgreSQL first. After= orders units; it does not wait for PostgreSQL to accept connections. If portal startup needs a live database, use a separate readiness check (for example a Quadlet ExecStartPre that waits on the port). Migration from bundled to external is manual with downtime.

flowchart LR
    subgraph plugins ["Proposed package responsibilities"]
        SS["Host admin frontend — owner to confirm"]
        BR["Config / setup / restart backend — owner TBD"]
        BC["backstage-rhaap-common"]
        AU["auth-backend-module-rhaap-provider"]
    end

    subgraph rhel ["RHEL VM Stack"]
        PG["postgres.service — Podman container"]
        PORTAL["portal.service — Backstage + plugins"]
        PG -->|Requires| PORTAL
    end

Consequences

Positive:

  • Reuse existing packages where appropriate; lazy-loaded admin code keeps bundle size small
  • Zero-config DB on VM matches OCP experience (where DB is auto-provisioned)

Negative:

  • Backend ownership and packaging must be resolved before implementation; Podman lifecycle to maintain on RHEL
  • Bundled-to-external DB migration requires downtime
  • Research: 002 (research not published in this repository), 005 (research not published in this repository), 006 (research not published in this repository)
  • workspaces/self-service/plugins/portal-scaffolder/, workspaces/aap/plugins/backstage-rhaap/, workspaces/aap/plugins/backstage-rhaap-common/, workspaces/aap/plugins/auth-backend-module-rhaap-provider/