chore: review and align the deployer-ui and backend bundle config contract

[hyde-repo]

chore: review and align the deployer-ui and backend bundle config contract

Wave: WAVE_04 (since 2026-06-05)
Related: #170 (deployer-ui bundle), #171 (backend bundle)

Status - it works

The bundles deploy the deployer-ui + backend on dev_deployer_ui_lab and the stack is functional end to end :
the backend container is up and healthy on :8000, the UI is up, and the backend reaches the Proxmox API. The
POC path is green.

Where things live

• deployer-ui bundle : range42-playbooks/bundles/admin/software.install.deployer-ui/
• backend bundle : range42-playbooks/bundles/admin/software.install.deployer-api-backend/
• scenario : range42-playbooks/scenarios/dev_deployer_ui_lab/
• bundle call-sites : scenarios/dev_deployer_ui_lab/02_dev_deployer_ui_lab_infrastructure/stage_01-vm_configure/dev-backend.yml and dev-deployer-ui.yml

The ask

The app and its containerisation have grown and largely live on your side now ; from the deployer-cli side we
mainly feed variables at deploy time. When you have bandwidth, could you take ownership of the deployer-ui +
backend bundles' app-facing config and flag what you would like to improve or align ? The aim is to keep the
config/wiring contract clean as the deployer-cli conventions evolve (key naming, workspace layout, vault).
No urgency.

Proposed split (simplest path)

• You : own the backend Dockerfile and the two bundles' app-facing config, iterating on dev_deployer_ui_lab.
• Us : feed the runtime variables to the containers at deploy, from the active workspace vault. Just tell
  us the interface you prefer - .env, a config file, or an API call - and we wire the bundle to feed it.

Context - a few spots we noticed (no pressure, just what we saw)

• Naming + structure : SSH key naming and the workspace/vault layout are moving to the deployer-cli
  convention (r42.<C>-<S>-...) ; the bundle bridges via symlinks for now. We will share the new layout so
  the app can read it directly and we drop the bridge.
• Vault keys : the Proxmox host seed reads 5 keys (proxmox_api_host/node/user/token_id/token_secret) ;
  the scenario vault example documents only one - we will fix the example on our side.
• SSH key unlocking in the container : the range42 SSH keys are passphrase-protected by default, and the
  backend's in-container ansible-runner needs them to reach the Proxmox jump + the VMs - with no interactive
  ssh-agent inside a container. How does the current backend unlock them (an in-container agent, the
  passphrase from the vault, or passphrase-less keys) ? Have you already planned this, or is it something to
  sort out together ?
• Your call, we adapt : how you would like the Git sources + PAT handed over, the scenarios/_universal
  entrypoint the backend runs, and whether the schema bootstrap (alembic upgrade head) stays app-side or
  bundle-side. Whatever you pick, we align the bundle.

[pparage]

Done range42-playbooks (fix/deployer-bundle-config-align)

• dev-backend call-site now sets DEPLOYER_UI_CORS_REGEX to match this lab's UI (r42.dev-deployer-ui / .190) — the bundle default targets r42.admin-deployer-ui and would block the browser.
• backend bundle README aligned to main.yml (alembic runs at deploy, two bind-mounts, PLAYBOOKS_DEST_DIR).
• dropped the stale scenarios/_universal references from the bundle.

Done range42-backend-api (fix/deploy-container-config-131)

• SSH unlock (your Q): the container now unlocks the passphrase-protected keys itself — decrypts the workspace vault with vault_pass.txt, starts an ssh-agent, and ssh-adds the keys via the same SSH_ASKPASS mechanism range42-context uses. Nothing changes on your side; keys stay passphrase-protected.
• compose bug: docker-compose.yml hard-coded API_BACKEND_WWWAPP_PLAYBOOKS_DIR=/app/, overriding the bundle's .env so the RO playbooks mount was never read. Now .env-driven.

Answers to the rest

• Interface: keep .env + your two seed API calls. 👍
• alembic: bundle-side (your main.yml already does it) — README now says so.
• _universal: retired — the backend will not use it.
• vault example: please don't add the 4 Proxmox keys — proxmox_api_host/node/user/token_id are auto-derived (host=ADDRESS:8006, user=range42_api@pam, token_id=r42_-), only token_secret is a real secret, so the example is already correct.

Commits: 05b614f · range42/range42-backend-api@ec8c1bf · range42/range42-backend-api@0a9dc2f

[pparage]

Took a pass at the app-facing config contract. Two PRs, both into dev:

• fix(dev_deployer_ui_lab): align backend bundle CORS + docs with app config contract #134 — scenario + bundle docs
• fix(deploy): container config contract — compose .env, in-container SSH unlock, Git PAT hardening range42-backend-api#112 — the backend side (compose, SSH unlock, Git PAT)

What changed

deployer-ui / backend bundles (playbooks #134)

• dev-backend call-site now sets DEPLOYER_UI_CORS_REGEX for this lab's UI (r42.dev-deployer-ui / .190) — the bundle default targets r42.admin-deployer-ui and would block the browser. ⚠️ the value is a guess (see below).
• backend bundle README aligned to main.yml (alembic at deploy, two bind-mounts, PLAYBOOKS_DEST_DIR).
• dropped the stale scenarios/_universal references.

backend-api (#112)

• SSH unlock (your Q): the container unlocks the passphrase-protected keys itself — decrypts the workspace vault with vault_pass.txt, starts an ssh-agent, and ssh-adds the keys via the same SSH_ASKPASS mechanism range42-context uses. Nothing changes on your side; keys stay passphrase-protected.
• compose bug: docker-compose.yml hard-coded API_BACKEND_WWWAPP_PLAYBOOKS_DIR=/app/, overriding the bundle .env, so the RO playbooks mount was never read. Now .env-driven.
• Git PAT hardening: token_ref is no longer returned by GET/POST /v1/catalog/sources (has_token boolean instead), catalog clones now authenticate with the token and redact it from errors, and the workspace clone no longer persists the token in .git/config.

Answers to the rest

• Interface: keep .env + your two seed API calls. 👍
• alembic: bundle-side (your main.yml already does it) — README now says so.
• _universal: retired — the backend will not use it.
• vault example: please don't add the 4 Proxmox keys — proxmox_api_host/node/user/token_id are auto-derived (host=ADDRESS:8006, user=range42_api@pam, token_id=r42_-); only token_secret is a real secret, so the example is already correct.

Still needs you

• CORS value is a guess (ssh-name + .190) — what origin do you actually browse the UI from? (tailnet?) I'll amend.
• Git PAT seed: the endpoint is now safe to seed except token-at-rest is still cleartext in SQLite (needs a secret-store decision on our side). Once that lands: POST /v1/catalog/sources + a github_pat vault key + one seed play, same shape as your Proxmox host.
• The SSH symlink bridge can go once we align the backend's key naming to r42.<C>-<S>-....