feat: scaffold Backstage application

[scotwells]

Summary

Scaffolds Datum's Backstage developer portal and software catalog, and wires up CI to publish the backend image plus a kustomize deployment bundle via the shared datum-cloud/actions reusable workflows, gated by a kind-based end-to-end test that actually boots Backstage.

What's included

• A standard Backstage monorepo generated with the official @backstage/create-app scaffolder: packages/app (frontend), packages/backend (backend), plus app-config.yaml, app-config.production.yaml, example entities/template, and the backend Dockerfile.
• A Datum-specific README.md with local-dev (yarn install && yarn dev) and build instructions.

Image + bundle publishing (shared actions)

• .github/workflows/publish.yaml replaces the bespoke build-image.yaml and uses the datum-cloud/actions reusable workflows pinned at v1.16.0:
  • publish-docker.yaml builds and pushes the backend image to ghcr.io/datum-cloud/backstage (context ., dockerfile packages/backend/Dockerfile, linux/amd64).
  • publish-kustomize-bundle.yaml then publishes the config/ tree as an OCI artifact to oci://ghcr.io/datum-cloud/backstage-kustomize, pinning the freshly built image into config/base via kustomize edit set image.

Dockerfile switched to self-contained multi-stage

• The scaffold shipped Backstage's host-build Dockerfile, which only COPYs a pre-built skeleton.tar.gz/bundle.tar.gz and assumes yarn install && yarn tsc && yarn build:backend already ran on the host. The shared publish workflow and the e2e job both run a plain docker build with no host yarn step, so that variant would fail.
• It is now the official multi-stage Dockerfile that runs yarn install --immutable, yarn tsc, and the backend build inside the image from the repo-root context. A plain docker build -f packages/backend/Dockerfile . now succeeds (verified locally end-to-end).
• The scaffold also shipped a stale Yarn v1 format yarn.lock that made yarn install --immutable fail under Yarn 4. It has been regenerated as a valid Yarn 4 (Berry) lockfile, and .dockerignore no longer excludes packages/*/src or plugins so the in-image build has its sources.

Deployment bundle (config/)

• config/base/: namespace, service account, a ClusterIP service on 7007, and a Deployment running the backend image with readiness/liveness probes on the new-backend health endpoints (/.backstage/health/v1/readiness and /.backstage/health/v1/liveness). The kustomization carries an images entry for ghcr.io/datum-cloud/backstage so the bundle publisher can pin the built tag. Database and app-config come from the overlay, not hardcoded here.
• config/test/: an e2e overlay that boots Backstage without GCP secrets or SSO. It adds an ephemeral postgres:16-alpine, an app-config.e2e.yaml ConfigMap (guest auth, default auth policy disabled, pg database pointed at the in-cluster postgres, github integrations/providers removed, a small static example catalog), and a Deployment patch that mounts the config, wires the DB env, and pins the image to the kind-loaded backstage:e2e.

Kind e2e gate

• .github/workflows/e2e.yaml runs on pull_request and pushes to main. It builds the backend image (buildx with GitHub Actions layer caching so the slow yarn install / tsc / build:backend layers are reused across runs), loads it into a kind cluster, applies config/test, waits for the postgres and backstage rollouts, and asserts the readiness, liveness, and catalog API endpoints all return HTTP 200. On failure it dumps pods, the deployment description, and backend logs.

Verified locally

• docker build -f packages/backend/Dockerfile . succeeds and produces a runnable image.
• A real kind cluster came up, deployed config/test, Backstage rolled out against postgres, the health endpoints returned 200, and the catalog API served the static example entities.

Notes

• Dependencies are not committed; node_modules are installed in CI / inside the image build.
• The published backend image is ghcr.io/datum-cloud/backstage; the published bundle is ghcr.io/datum-cloud/backstage-kustomize.
• The catalog org-model and production deploy wiring for this app live in the datum-cloud/infra repo, not here.

Design proposal: https://github.com/datum-cloud/infra/blob/main/docs/enhancements/backstage-service-catalog/README.md

Branding

Applies Datum's brand to the app (new frontend system, theme extensions):

• Datum-branded light and dark themes in packages/app/src/theme/datum.ts (createUnifiedTheme): Midnight Fjord #0C1D31 primary and navy sidebar, Pine Forge #4D6356 secondary, Aurora Moss #E6F59F selected-indicator (paired with dark/white text, never white text on the lime), flat navy page headers (no gradient), and status colors. Registered via ThemeBlueprint in a new packages/app/src/modules/theme module; the built-in Backstage themes are disabled in app-config.yaml and Datum Light is the default.
• Datum logos inlined into packages/app/src/modules/nav/LogoFull.tsx (lime mark + white wordmark for the navy sidebar) and LogoIcon.tsx (lime mark for the collapsed sidebar). Added packages/app/public/favicon.svg (navy mark) referenced from index.html, with the generic Backstage favicon.ico left as fallback. App title set to "Datum Portal".
• Fonts: the theme references the brand families (Canela Text headings, Alliance No.1 body) first for forward-compatibility, but we decided to use fallback fonts. The licensed brand fonts are intentionally not bundled (this is a public repo) — no .woff2 committed — and the fallback stacks (Georgia serif for headings, system sans for body) render cleanly on their own. They can optionally be added out-of-band later.

Security hardening

Applies a batch of security findings. Auth/guest config is intentionally untouched — an OIDC proxy will front the app at deploy time.

• Gate publishing (H-2): publish.yaml no longer triggers on pull requests or arbitrary branch pushes. The image and kustomize bundle now ship only on main, v* tags, and published releases. PR validation is covered by the e2e build.
• Isolate PR build cache (M-1): e2e.yaml builds untrusted PR code, so its buildx GHA cache now uses its own scope=backstage-e2e for both cache-from and cache-to, preventing it from poisoning the trusted publish build's cache.
• e2e least-privilege (L-1): Added a top-level permissions: { contents: read } to e2e.yaml.
• SHA-pin actions (L-2): Every third-party marketplace action in e2e.yaml (actions/checkout, docker/setup-buildx-action, docker/build-push-action, helm/kind-action) is pinned to a full commit SHA with a trailing version comment, matching the org convention. First-party datum-cloud/actions/...@v1.16.0 reusable workflows stay tag-pinned by convention.
• Deployment hardening (M-2): config/base/deployment.yaml now disables service-account token automount, runs as non-root uid/gid 1000 with fsGroup and the RuntimeDefault seccomp profile, drops all capabilities, disables privilege escalation, and mounts the root filesystem read-only. Writable emptyDirs are mounted at /tmp and /home/node/.cache so the backend can write under readOnlyRootFilesystem. CPU/memory requests and a CPU limit were added. Validated end-to-end on kind: the backend rolls out with zero restarts, readOnlyRootFilesystem holds, and readiness/liveness/catalog all return 200.
• Snyk scanning: New snyk-scan.yaml calls the shared datum-cloud/actions reusable workflow on pushes to main, pull requests, and a weekly schedule, with the permissions needed for SARIF upload. Prerequisite: this requires a SNYK_TOKEN org secret to be present; the workflow will fail authentication until it is added.
• Dependabot: New .github/dependabot.yml covering the npm (root, weekly, grouped minor/patch) and github-actions (weekly) ecosystems.
• Dependency advisories (M-4): Added root resolutions to force-bump the three high-severity packages to patched releases within their compatible majors (undici 7.24.7 → 7.28.0, scoped to the 7.x descriptor; protobufjs → 7.6.4; tar → 7.5.16) plus a yarn dedupe. High-severity advisories dropped from 3 affected packages (14 advisory entries) to 0; typecheck, app build, and the kind e2e all stay green.
• Repo settings: Secret scanning and push protection are enabled on the repo.

Next steps

• Wire app-config catalog providers, auth, and Kubernetes integration for production.
• Add the production overlay / deploy wiring and populate the catalog org-model in datum-cloud/infra.
• Add the SNYK_TOKEN org secret so the Snyk scan can authenticate.

https://claude.ai/code/session_01NMSkwUcaTmZr7S5XmV2aFG