Establish a secure, persistent hosted deployment #30

Open
opened 2026-11-07 21:51:25 +00:00 by martin · 1 comment
Owner

Summary

Establish and verify a secure, persistent hosted Backstage deployment in the cluster's dev and prod environments. This issue is the integration gate; application work is in this repository and Kubernetes/GitOps work is in Personal/cluster.

Context

  • Local development uses guest authentication and in-memory SQLite; the production configuration still contains demo catalog locations and is not an approved hosted security model.
  • The hosting target is the Nixidy/ArgoCD cluster repository, Personal/cluster. The intended public URLs are https://backstage.dev.martials.no and https://backstage.martials.no. An existing PostgreSQL instance runs on Nidaros, but cluster connectivity has not yet been tested.
  • Foundation work #20, #21, #22, #23, and #24 is complete. Node 24 was validated in #47.
  • #32 implements Keycloak SSO in the application. SSO does not define authorization.
  • Personal/cluster#88 tracks the Nixidy dev/prod deployment, ingress, configuration, and secret wiring. #62 tracks shared Bun CI/CD adoption; it depends on the Backstage-compatible global workflow path in Personal/nixos-configuration#71.

Scope

  • Configure the Backstage application for hosted use: intended catalog sources, authentication, authorization, and private-data boundaries.
  • Complete the cluster-side deployment through Personal/cluster#88; do not duplicate its manifest and SOPS details here.
  • Publish the validated application image and promote it through reviewable cluster GitOps PRs; the app pipeline must not deploy directly. This work is tracked in #62.
  • Validate persistence, recovery, and operating procedures for the hosted service.

Acceptance criteria

  • Hosted configuration uses only intended catalog locations; demo sources are absent. The production catalog provider is enabled with required backend-only credentials and continues refreshing catalog data.
  • Complete #32: authorized users receive the expected catalog identity, invalid or unmapped identities are rejected, and guest access cannot bypass hosted sign-in.
  • Define and enforce authorization for catalog reads and mutations, TechDocs/private metadata, templates, and enabled actions. Verify allowed and denied access; private data is visible only to intended users.
  • Complete #62: publish a versioned image only after Backstage validation passes, and promote dev/prod image updates through reviewable GitOps PRs; application CI does not deploy directly.
  • Complete and verify Personal/cluster#88 for both environments, including HTTPS routing to the intended public URLs and backend-only secret/configuration injection.
  • Evaluate the existing Nidaros PostgreSQL service from both cluster environments. Use it only if access can be restricted and encrypted; otherwise select a suitable persistent alternative. Verify database state survives backend pod replacement and a backup can be restored.
  • Publish TechDocs from CI to private object storage as decided in #25, with CI write-only and backend read-only credentials. Verify the deployed backend can read published docs; keep private docs disabled until the authorization policy above is in place.
  • Verify image startup, health monitoring, and rollback in the hosted environment; document operating and recovery procedures.

Dependencies

Out of scope

  • Phase 2 workflow pilots are not prerequisites for the first secure hosted deployment, as recorded in #31.
  • Deploying a new Keycloak instance or expanding Backstage's feature set beyond the hosted security and operations gate.
## Summary Establish and verify a secure, persistent hosted Backstage deployment in the cluster's dev and prod environments. This issue is the integration gate; application work is in this repository and Kubernetes/GitOps work is in Personal/cluster. ## Context - Local development uses guest authentication and in-memory SQLite; the production configuration still contains demo catalog locations and is not an approved hosted security model. - The hosting target is the Nixidy/ArgoCD cluster repository, [Personal/cluster](https://code.martials.no/Personal/cluster). The intended public URLs are `https://backstage.dev.martials.no` and `https://backstage.martials.no`. An existing PostgreSQL instance runs on Nidaros, but cluster connectivity has not yet been tested. - Foundation work #20, #21, #22, #23, and #24 is complete. Node 24 was validated in #47. - [#32](https://code.martials.no/Personal/backstage/issues/32) implements Keycloak SSO in the application. SSO does not define authorization. - [Personal/cluster#88](https://code.martials.no/Personal/cluster/issues/88) tracks the Nixidy dev/prod deployment, ingress, configuration, and secret wiring. [#62](https://code.martials.no/Personal/backstage/issues/62) tracks shared Bun CI/CD adoption; it depends on the Backstage-compatible global workflow path in Personal/nixos-configuration#71. ## Scope - Configure the Backstage application for hosted use: intended catalog sources, authentication, authorization, and private-data boundaries. - Complete the cluster-side deployment through Personal/cluster#88; do not duplicate its manifest and SOPS details here. - Publish the validated application image and promote it through reviewable cluster GitOps PRs; the app pipeline must not deploy directly. This work is tracked in #62. - Validate persistence, recovery, and operating procedures for the hosted service. ## Acceptance criteria - [ ] Hosted configuration uses only intended catalog locations; demo sources are absent. The production catalog provider is enabled with required backend-only credentials and continues refreshing catalog data. - [ ] Complete #32: authorized users receive the expected catalog identity, invalid or unmapped identities are rejected, and guest access cannot bypass hosted sign-in. - [ ] Define and enforce authorization for catalog reads and mutations, TechDocs/private metadata, templates, and enabled actions. Verify allowed and denied access; private data is visible only to intended users. - [ ] Complete #62: publish a versioned image only after Backstage validation passes, and promote dev/prod image updates through reviewable GitOps PRs; application CI does not deploy directly. - [ ] Complete and verify [Personal/cluster#88](https://code.martials.no/Personal/cluster/issues/88) for both environments, including HTTPS routing to the intended public URLs and backend-only secret/configuration injection. - [ ] Evaluate the existing Nidaros PostgreSQL service from both cluster environments. Use it only if access can be restricted and encrypted; otherwise select a suitable persistent alternative. Verify database state survives backend pod replacement and a backup can be restored. - [ ] Publish TechDocs from CI to private object storage as decided in #25, with CI write-only and backend read-only credentials. Verify the deployed backend can read published docs; keep private docs disabled until the authorization policy above is in place. - [ ] Verify image startup, health monitoring, and rollback in the hosted environment; document operating and recovery procedures. ## Dependencies - Native prerequisites #20, #21, #22, #23, and #24 are complete. - #32 (Keycloak SSO), #62 (image publication and promotion workflow), and Personal/cluster#88 (cluster deployment) are mandatory gates. ## Out of scope - Phase 2 workflow pilots are not prerequisites for the first secure hosted deployment, as recorded in #31. - Deploying a new Keycloak instance or expanding Backstage's feature set beyond the hosted security and operations gate.
Author
Owner

Existing deployment precedent from the vault

Use the documented platform implementation as the starting point before asking for a new deployment design:

Evaluate reuse of the existing Nix/OCI/GitOps path before inventing a parallel Docker-only deployment pipeline. These precedents do not yet establish that Backstage can use the Astro-oriented global workflows unchanged. Coordinate #20/#22, preserve the Bun-before-deployment dependency, and verify current configuration, persistence, identity/authorization, and private-data boundaries.

## Existing deployment precedent from the vault Use the documented platform implementation as the starting point before asking for a new deployment design: - [`projects/toolbox/learnings.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/toolbox/learnings.md): locked Bun dependencies, Nix-built OCI images, and production-startup tests exercising the same compiled artifact as deployment. - [`projects/nixos/woodpecker-global-workflow-architecture.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/nixos/woodpecker-global-workflow-architecture.md): validate → publish image to Forgejo registry → open dev/prod cluster promotion PR, rather than directly deploying from application CI. - [`projects/cluster/ci-woodpecker-pipelines.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/cluster/ci-woodpecker-pipelines.md): Nixidy/GitOps manifest generation and promotion conventions. - [`projects/cluster/secret-management-sops.md`](https://code.martials.no/Personal/context-vault/src/branch/main/projects/cluster/secret-management-sops.md): reference for existing secret-management conventions; verify the current implementation before adoption. Evaluate reuse of the existing Nix/OCI/GitOps path before inventing a parallel Docker-only deployment pipeline. These precedents do not yet establish that Backstage can use the Astro-oriented global workflows unchanged. Coordinate #20/#22, preserve the Bun-before-deployment dependency, and verify current configuration, persistence, identity/authorization, and private-data boundaries.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/backstage#30
No description provided.