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
Related¶
- 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/