feature/backstage (#13)

Reviewed-on: #13
Reviewed-by: gitea_admin <admin@forteapps.net>
Co-authored-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>
Co-committed-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>

docs/REFERENCE.md

@@ -965,6 +965,83 @@ ignore:
 - Check Gitea Actions tab for workflow run status and logs
 - Monitor Anthropic usage dashboard for token consumption
 
+### Backstage / RHDH (Developer Portal)
+
+**Chart**: `backstage` (RHDH — Red Hat Developer Hub)
+**Version**: `5.8.0`
+**Namespace**: `backstage`
+**Helm Repo**: `https://redhat-developer.github.io/rhdh-chart`
+**Image**: `quay.io/rhdh-community/rhdh:next`
+
+**Purpose**: Internal developer portal where teams register and broadcast themselves, their applications, APIs, and systems. Provides a unified catalog, templates, and documentation hub.
+
+**Why RHDH over vanilla Backstage**: Ships 27+ plugins pre-bundled (ArgoCD, Kubernetes, Keycloak, GitHub, GitLab, Jira, SonarQube, Tekton, Jenkins, Quay, and more). Supports dynamic plugin installation at runtime — no image rebuilds needed.
+
+**Configuration** (`infra/values/base/backstage-values.yaml`):
+- OpenShift Route disabled (`route.enabled: false`) — uses Traefik ingress instead
+- PostgreSQL subchart enabled for persistence (2Gi)
+- SecurityContext configured for vanilla Kubernetes (non-OpenShift)
+- Traefik ingress with `websecure` entrypoint
+- App title: "Forte Developer Portal"
+- Dynamic plugins: loads `dynamic-plugins.default.yaml` (all 27+ bundled plugins)
+- Catalog rules: Component, System, API, Resource, Location, Template, Group, User, Domain
+
+**Authentication** (Keycloak OIDC):
+- Uses the self-service registrar pattern (see [Keycloak Client Registrar](#keycloak-client-registrar))
+- Config Secret: `cluster-resources/backstage-keycloak-client-config.yaml`
+- Kyverno clones it → registrar creates `backstage-oidc-credentials` Secret in `backstage` namespace
+- Credential keys: `AUTH_OIDC_CLIENT_ID`, `AUTH_OIDC_CLIENT_SECRET` (loaded via `extraEnvVarsSecrets`)
+- Redirect URI: `https://backstage.forteapps.net/api/auth/oidc/handler/frame`
+- Sign-in resolver: `emailMatchingUserEntityProfileEmail`
+
+**Catalog Discovery** (Gitea):
+- Auto-discovers `catalog-info.yaml` from all repos in the `Forte` organization
+- Scans every 30 minutes via the Gitea catalog provider plugin
+- Gitea SCM integration configured for URL resolution (`git.forteapps.net`)
+
+**Catalog Registration**:
+Teams register services by adding a `catalog-info.yaml` to their repo root:
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-service
+  description: My service description
+  annotations:
+    backstage.io/source-location: url:https://git.forteapps.net/Forte/my-service
+spec:
+  type: service
+  lifecycle: production
+  owner: team-name
+```
+
+Repos with this file are auto-discovered — no manual registration needed.
+
+**Dynamic Plugins**:
+Add plugins at runtime via `global.dynamic.plugins` in values — no image rebuild:
+```yaml
+global:
+  dynamic:
+    plugins:
+    - package: "@scope/my-plugin@1.0.0"
+      integrity: "sha512-..."
+```
+
+**Per-cluster Configuration** (`infra/values/upc-dev/backstage-values.yaml`):
+```yaml
+global:
+  host: backstage.forteapps.net
+upstream:
+  backstage:
+    appConfig:
+      app:
+        baseUrl: https://backstage.forteapps.net
+      backend:
+        baseUrl: https://backstage.forteapps.net
+  ingress:
+    host: backstage.forteapps.net
+```
+
 ### Keycloak Client Registrar
 
 **Type**: CronJob (deployed via Keycloak Helm chart `extraDeploy`)