Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: Betrieb mit PostgreSQL

Ziel: Du stellst das Portal auf PostgreSQL um, baust es wie für die Produktion und betreibst Frontend und Backend als einen Node-Prozess auf Port 7007 – konfiguriert über Dateien und Umgebungsvariablen. · Dauer: ca. 90 min · Voraussetzung: Tag 12

Briefing

  • SQLite ist eine Lab-Abkürzung: eine Datei pro Plugin, nur ein Prozess, keine Backups im laufenden Betrieb, Suche nur als Lunr im RAM. Produktiv: PostgreSQL.
  • Backstage legt in Postgres pro Plugin eine Datenbank an (backstage_plugin_catalog, …_search, …) und migriert die Tabellen selbst.
  • Der Produktions-Build (yarn build:backend) packt Backend und gebautes Frontend in bundle.tar.gz. Das Plugin app-backend liefert die App aus – ein Prozess, eine Adresse.
  • Konfiguration: mehrere --config-Dateien, später gewinnt; Secrets per ${ENV}, Einzelwerte per APP_CONFIG_*.
 dev (yarn start)                       Produktion (node packages/backend)
 ┌───────────────┐  ┌───────────────┐   ┌──────────────────────────────────┐
 │ Frontend :3000│─►│ Backend :7007 │   │ :7007  app-backend  /  (App)     │
 │ (Dev-Server)  │  │ SQLite → pg   │   │        Plugins      /api/…       │
 └───────────────┘  └──────┬────────┘   └───────────────┬──────────────────┘
                           └─────────────┬──────────────┘
                              Container bs-postgres  127.0.0.1:5432
                              backstage_plugin_catalog, …_search, …

Vorausgesetzt wird der Stand Ende Tag 12: Katalog mit Gitea-Provider, Organisation aus kranich/org, Templates aus kranich/templates.

Drill 1: PostgreSQL im Container

Das Passwort ist ein Lab-Wert und liegt in einer Datei, nicht in der YAML-Konfiguration:

mkdir -p ~/backstage-lab/tag13 && cd ~/backstage-lab/tag13
cp ~/backstage-lab/code/tag13/pg.env . && chmod 600 pg.env
cat pg.env

Erwartet:

# pg.env – Zugang zur Lab-Datenbank (Lab-Werte!). Laden mit: source pg.env
export POSTGRES_HOST=127.0.0.1
export POSTGRES_PORT=5432
export POSTGRES_USER=backstage
export POSTGRES_PASSWORD=lab-pg-pw-123
source pg.env
docker run -d --name bs-postgres -p "127.0.0.1:$POSTGRES_PORT:5432" \
  -v bs-postgres-data:/var/lib/postgresql/data \
  -e POSTGRES_USER -e POSTGRES_PASSWORD \
  postgres:16.4-alpine
until docker exec bs-postgres pg_isready -h 127.0.0.1 -U backstage; do sleep 1; done
docker exec bs-postgres psql -U backstage -Atc 'select version()' | cut -c1-40

Erwartet:

c4d4aaa233aa5fc94fd90e0c3a2863f0f0a7b6643dfe0fbc98bb8add49ab7e8d
127.0.0.1:5432 - accepting connections
PostgreSQL 16.4 on aarch64-unknown-linux

-e POSTGRES_USER ohne Wert übernimmt die Variable aus deiner Shell. Das Image legt damit einen Superuser backstage an; die Daten liegen im Volume bs-postgres-data und überleben docker rm. Warum -h 127.0.0.1? Beim ersten Start läuft kurz ein Init-Server nur auf dem Unix-Socket – erst die TCP-Antwort heißt wirklich „bereit”.

Achtung: Belegt schon ein anderes Postgres (z. B. aus Homebrew) Port 5432, meldet docker run „port is already allocated”. Dann in pg.env z. B. 5433 eintragen, Container löschen (docker rm -f bs-postgres) und neu starten.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Portal auf PostgreSQL umstellen

In app-config.local.yaml ersetzt du den SQLite-Block durch dieselbe Form wie in der app-config.production.yaml der create-app-Vorlage: client: pg, alle Werte aus Umgebungsvariablen.

source ~/backstage-lab/setup/env.sh
cd ~/backstage-lab/portal
cp app-config.local.yaml app-config.local.yaml.sqlite
yq -i '.backend.database = {"client": "pg", "connection": {
  "host": "${POSTGRES_HOST}", "port": "${POSTGRES_PORT}",
  "user": "${POSTGRES_USER}", "password": "${POSTGRES_PASSWORD}"}}' \
  app-config.local.yaml
yq '.backend.database' app-config.local.yaml

Erwartet:

client: pg
connection:
  host: ${POSTGRES_HOST}
  port: ${POSTGRES_PORT}
  user: ${POSTGRES_USER}
  password: ${POSTGRES_PASSWORD}

portal.sh muss die Variablen kennen. Damit jedes neue Terminal sie hat, hängst du pg.env an env.sh an (wie die venv an Tag 7):

echo 'if [ -f "$LAB/tag13/pg.env" ]; then source "$LAB/tag13/pg.env"; fi' \
  >> ~/backstage-lab/setup/env.sh
source ~/backstage-lab/setup/env.sh && echo "$POSTGRES_HOST:$POSTGRES_PORT"
~/backstage-lab/setup/portal.sh restart
docker exec bs-postgres psql -U backstage -lqt | cut -d'|' -f1 | grep backstage

Erwartet:

127.0.0.1:5432
✔ gestoppt
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
 backstage
 backstage_plugin_app
 backstage_plugin_auth
 backstage_plugin_catalog
 backstage_plugin_kubernetes
 backstage_plugin_mcp-actions
 backstage_plugin_notifications
 backstage_plugin_permission
 backstage_plugin_proxy
 backstage_plugin_scaffolder
 backstage_plugin_search
 backstage_plugin_signals
 backstage_plugin_techdocs
 backstage_plugin_user-settings

Warum so viele Datenbanken? Standard ist pluginDivisionMode: database – jedes Plugin bekommt eine eigene Datenbank mit Präfix backstage_plugin_ und darf nur seine eigenen Tabellen sehen. Dafür braucht der DB-User das Recht CREATEDB. Die Datenbank backstage hat das Image angelegt, Backstage nutzt sie nicht.

Die neue Datenbank ist leer. Der Katalog füllt sich in den ersten Minuten wieder aus Konfiguration und Gitea-Provider. Verloren sind nur Daten, die allein in SQLite lagen: Sterne/Favoriten, Benachrichtigungen, alte Scaffolder-Tasks. Die SQLite-Dateien in ~/backstage-lab/data bleiben liegen.

Fortschritt speichern? Kostenlos registrieren

Drill 3: In die Datenbank geschaut

Was der Katalog speichert, liegt jetzt in normalen Tabellen:

sql() { docker exec bs-postgres psql -U backstage -d "$1" -Atc "$2"; }
sql backstage_plugin_catalog "select tablename from pg_tables
  where schemaname = 'public' and tablename not like '%knex%'
  and tablename not like 'backstage_%' order by 1"
sql backstage_plugin_catalog "select final_entity::json->>'kind', count(*)
  from final_entities group by 1 order by 1"

Erwartet (gekürzt, Zahlen hängen von deinem Katalog ab):

final_entities
location_update_log
locations
refresh_keys
refresh_state
refresh_state_references
relations
search
stitch_queue
API|2
Component|3
Group|6
Location|5
System|1
User|5

final_entities hält jede Entity als fertiges JSON, refresh_state steuert die Verarbeitung, die Tabelle search dient den Filtern der Katalog-API (nicht der Volltextsuche). Und die Suche?

sed 's/\x1b\[[0-9;]*m//g' $LAB/portal.log \
  | grep -c 'Postgres search engine is not supported'
sql backstage_plugin_search "select type, count(*) from documents group by 1"

Erwartet:

0
software-catalog|22

Die Warnung aus Tag 8 ist weg: Das Modul search-backend-module-pg erkennt Postgres und registriert sich als Engine, der Index liegt in der Tabelle documents. Sobald der TechDocs-Kollator gelaufen ist, kommt eine Zeile techdocs dazu. Der Beweis für den Unterschied zu Lunr:

~/backstage-lab/setup/portal.sh restart
bs 'search/query?term=sendung' | jq -r '.results[].document.title'

Erwartet (gekürzt):

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
sendungs-api
sendungs-api
Team Sendung
tracking-web

Direkt nach dem Neustart gibt es Treffer – kein HTTP 500 mit MissingIndexError mehr wie an Tag 8. Im Portal unter Search sieht es aus wie in der Abbildung.

Suchergebnisse aus dem Postgres-Index direkt nach dem Neustart

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der Produktions-Build

yarn start übersetzt alles im Speicher und braucht rund 2 GB RAM. Für den Betrieb baust du einmal vorab. Das Portal muss dafür nicht laufen:

~/backstage-lab/setup/portal.sh stop
cd ~/backstage-lab/portal
time yarn tsc
time yarn build:backend
ls -lh packages/backend/dist | awk 'NR>1 {print $5, $9}'
du -sh packages/app/dist

Erwartet (Dauer hängt stark vom Rechner ab):

✔ gestoppt
yarn tsc  3,87s user 0,66s system 117% cpu 3,852 total
yarn build:backend  16,17s user 3,18s system 225% cpu 8,591 total
15M bundle.tar.gz
895B skeleton.tar.gz
 66M    packages/app/dist

yarn tsc prüft nur die Typen (ohne Fehler keine Ausgabe). yarn install --immutable aus dem Kommentar im Dockerfile brauchst du lokal nicht – deine node_modules sind aktuell. Was steckt in den Archiven?

tar tzf packages/backend/dist/skeleton.tar.gz
tar tzf packages/backend/dist/bundle.tar.gz | cut -d/ -f1-3 | sort -u | head -8

Erwartet:

packages/app/package.json
packages/backend/package.json
./
package.json
packages/
packages/app/
packages/app/dist
packages/app/package.json
packages/backend/
packages/backend/dist

Warum zwei Archive? Das Skeleton enthält nur die package.json-Dateien – genug für yarn install im Docker-Build, der so im Cache bleibt, solange sich Abhängigkeiten nicht ändern. Das Bundle bringt den gebauten Code. build:backend baut alle Workspace-Pakete mit, von denen backend abhängt, darunter packages/app (im Log: „Building app separately because it is a bundled package”) und dein Backend-Plugin aus Tag 11. Ein eigenes yarn workspace app build ist nicht nötig.

Fortschritt speichern? Kostenlos registrieren

Drill 5: app-config.production.yaml

Die Vorlage aus create-app bringt schon client: pg, aber auch die Beispiel-Locations. Du ersetzt sie durch eine Datei, die festlegt, was in Produktion anders ist:

cd ~/backstage-lab/portal
cp app-config.production.yaml app-config.production.yaml.vorlage
cp ~/backstage-lab/code/tag13/app-config.production.yaml .
cat app-config.production.yaml
# app-config.production.yaml – Tag 13: Produktionsbetrieb, ein Prozess auf :7007
# Keine Secrets in dieser Datei: alles Geheime kommt per ${ENV} herein.
app:
  # Frontend und Backend unter derselben Adresse (app-backend liefert die App aus)
  baseUrl: http://localhost:7007
backend:
  baseUrl: http://localhost:7007
  listen: ':7007'
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
auth:
  providers:
    guest:
      # Nur fürs Lab! Ohne NODE_ENV=development lehnt der Guest-Provider sonst ab.
      dangerouslyAllowOutsideDevelopment: true
catalog:
  # Ersetzt die Liste aus app-config.local.yaml: keine file-Locations in Produktion
  locations:
    - type: url
      target: http://127.0.0.1:3300/kranich/katalog/src/branch/main/locations.yaml
    - type: url
      target: http://127.0.0.1:3300/kranich/org/src/branch/main/org.yaml
      rules:
        - allow: [User, Group]
    - type: url
      target: http://127.0.0.1:3300/kranich/templates/src/branch/main/templates.yaml

Drei Punkte sind neu. app.baseUrl gleich backend.baseUrl, weil es keinen Dev-Server mehr gibt. catalog.locations ersetzt die Liste komplett (Arrays werden nicht gemischt, Tag 3): Die file-Locations ../../examples/… gelten relativ zum Arbeitsverzeichnis des Prozesses – bei yarn start ist das packages/backend, im Betrieb das Wurzelverzeichnis. Die Beispiel-Entities fallen damit weg (Orphans). Und der Guest-Provider prüft NODE_ENV: Alles außer development gilt als Produktion. Falls du an Tag 12 den Guest-Provider entfernt hast, lass den auth-Block weg – der OIDC-Login funktioniert unverändert, weil sein Callback ohnehin über Port 7007 läuft.

Welche Werte am Ende gelten, zeigt config:print – Secrets maskiert:

yarn backstage-cli config:print --config app-config.yaml \
  --config app-config.local.yaml --config app-config.production.yaml \
  2>/dev/null | yq '.backend.database, .app.baseUrl'
env -u POSTGRES_PASSWORD yarn backstage-cli config:print --config app-config.yaml \
  --config app-config.production.yaml 2>/dev/null | yq '.backend.database.connection'

Erwartet:

client: pg
connection:
  host: 127.0.0.1
  port: "5432"
  user: backstage
  password: <secret>
http://localhost:7007
host: 127.0.0.1
port: "5432"
user: backstage

Fehlt eine Variable, verschwindet der Schlüssel still – kein Fehler beim Laden, erst der Login an der Datenbank scheitert. ${VAR:-default} setzt einen Ersatzwert, $$ schützt ein echtes Dollarzeichen.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ein Prozess auf Port 7007

Im Docker-Image wird das Bundle in ein leeres Verzeichnis entpackt und dort mit yarn workspaces focus --all --production installiert. Lokal sparst du dir die Installation: Ein APFS-Klon (cp -c) deiner node_modules kostet keinen Plattenplatz.

rm -rf ~/backstage-lab/release && mkdir ~/backstage-lab/release
cd ~/backstage-lab/release
tar xzf ../portal/packages/backend/dist/bundle.tar.gz
cp -c -R ../portal/node_modules .
cp ../portal/app-config.yaml ../portal/app-config.local.yaml \
  ../portal/app-config.production.yaml .
ls

Erwartet:

app-config.local.yaml
app-config.production.yaml
app-config.yaml
node_modules
package.json
packages
yarn.lock

Der Klon funktioniert, weil die Workspace-Links relativ sind (node_modules/app -> ../packages/app) und jetzt auf die gebauten Pakete im Release zeigen. Start im Hintergrund, mit allen Variablen aus env.sh und pg.env:

source ~/backstage-lab/setup/env.sh
nohup node packages/backend --config app-config.yaml \
  --config app-config.local.yaml --config app-config.production.yaml \
  > ~/backstage-lab/prod.log 2>&1 & echo $! > ~/backstage-lab/prod.pid
until curl -sf $BACKSTAGE/.backstage/health/v1/readiness; do sleep 1; done; echo
head -3 ~/backstage-lab/prod.log | sed 's/\x1b\[[0-9;]*m//g' | cut -c1-88
grep -o 'Serving static app content from .*' ~/backstage-lab/prod.log
curl -s $BACKSTAGE/ | grep -o '<title>[^<]*'

Erwartet:

{"status":"ok"}
Loading config from MergedConfigSource{FileConfigSource{path="/Users/<du>/backstage-lab/
2026-10-13T07:44:27.860Z backstage info Found 4 new secrets in config that will be redac
2026-10-13T07:44:27.865Z rootHttpRouter info Listening on :7007
Serving static app content from /Users/<du>/backstage-lab/release/packages/app/dist
<title>Kranich Entwicklerportal

Der Prozess braucht nur einen Bruchteil des RAM von yarn start:

ps -o rss= -p "$(cat ~/backstage-lab/prod.pid)" | awk '{printf "%d MB\n", $1/1024}'

Erwartet (schwankt, bei mir zwischen gut 100 und 520 MB):

518 MB

Öffne http://localhost:7007 (nicht mehr 3000!) und melde dich mit Enter an. Erwartet: deine Startseite aus Tag 9, ausgeliefert vom Backend, wie in der Abbildung.

Startseite des Portals aus dem Produktions-Build auf Port 7007
  1. Klicke in der Sidebar auf Settings.
  2. Erwartet: In der Karte Backstage Identity steht deine User-Entity mit ihren Gruppen wie in der Abbildung – der Sign-in-Resolver arbeitet auch in Produktion.
Backstage Identity im Produktionsbetrieb
  1. Klicke auf Catalog. Erwartet: der Katalog wie in der Abbildung, ohne die Beispiel-Entities aus create-app.
Katalog aus dem Produktions-Build, Daten aus PostgreSQL

Tipp: Stoppen mit kill $(cat ~/backstage-lab/prod.pid). Nach jeder Code-Änderung gilt: yarn tsc, yarn build:backend, Release neu entpacken.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Konfiguration per Umgebung und Health-Endpunkte

Neben ${VAR} in YAML gibt es Overrides ohne Datei: Jede Variable APP_CONFIG_<pfad> mit _ als Trenner setzt einen Wert. Der Wert wird als JSON gelesen, sonst als Text. Neustart mit zwei Overrides:

cd ~/backstage-lab/release
kill $(cat ~/backstage-lab/prod.pid); sleep 3
APP_CONFIG_app_title='Kranich Portal (Prod)' \
APP_CONFIG_auth_providers_guest_dangerouslyAllowOutsideDevelopment=false \
nohup node packages/backend --config app-config.yaml \
  --config app-config.local.yaml --config app-config.production.yaml \
  > ~/backstage-lab/prod.log 2>&1 & echo $! > ~/backstage-lab/prod.pid
until curl -sf $BACKSTAGE/.backstage/health/v1/readiness >/dev/null; do sleep 1; done
head -1 ~/backstage-lab/prod.log | grep -o 'EnvConfigSource{[^}]*}'
curl -s $BACKSTAGE/ | grep -o '<title>[^<]*'
curl -s $BACKSTAGE/api/auth/guest/refresh -H 'X-Requested-With: XMLHttpRequest' \
  | jq -r .error.message | fold -w 88

Erwartet:

EnvConfigSource{count=2}
<title>Kranich Portal (Prod)
The guest provider cannot be used outside of a development environment unless 'auth.prov
iders.guest.dangerouslyAllowOutsideDevelopment' is enabled

Env-Overrides gewinnen gegen alle Dateien. Im Browser scheitert jetzt Enter mit der Meldung aus der Abbildung – genau das Fehlerbild, wenn Guest in Produktion nicht freigeschaltet ist.

Gast-Login im Produktionsbetrieb abgelehnt

Kubernetes und Load Balancer prüfen den Prozess über zwei Endpunkte ohne Login:

curl -s -w ' %{http_code}\n' $BACKSTAGE/.backstage/health/v1/liveness
docker stop bs-postgres >/dev/null
curl -s -w ' %{http_code}\n' $BACKSTAGE/.backstage/health/v1/readiness
bs 'catalog/entities?limit=1' -S 2>&1 | tail -1
docker start bs-postgres >/dev/null; sleep 4
bs 'catalog/entities?limit=1' | jq length

Erwartet (gekürzt):

{"status":"ok"} 200
{"status":"ok"} 200
curl: (22) The requested URL returned error: 500
1

liveness heißt „Prozess lebt”, readiness „fertig gestartet, nimmt Anfragen an” (während des Starts: 503 „Backend has not started yet”). Die Datenbank prüft keiner der beiden – fällt Postgres aus, antworten die APIs mit 500 und erholen sich ohne Neustart, sobald die Datenbank zurück ist.

Zum Schluss wieder der normale Start (Gast erlaubt, Originaltitel):

kill $(cat ~/backstage-lab/prod.pid); sleep 3
nohup node packages/backend --config app-config.yaml \
  --config app-config.local.yaml --config app-config.production.yaml \
  > ~/backstage-lab/prod.log 2>&1 & echo $! > ~/backstage-lab/prod.pid

Fortschritt speichern? Kostenlos registrieren

Drill 8: Logs als JSON

Mit NODE_ENV=production schreibt der Logger JSON statt farbigem Text – lesbar für Loki, Elasticsearch oder Splunk:

kill $(cat ~/backstage-lab/prod.pid); sleep 3
NODE_ENV=production nohup node packages/backend --config app-config.yaml \
  --config app-config.local.yaml --config app-config.production.yaml \
  > ~/backstage-lab/prod.log 2>&1 & echo $! > ~/backstage-lab/prod.pid
until curl -sf $BACKSTAGE/.backstage/health/v1/readiness >/dev/null; do sleep 1; done
sed -n 3p ~/backstage-lab/prod.log
grep '^{' ~/backstage-lab/prod.log | jq -r 'select(.level == "warn") | .message' \
  | cut -c1-70 | sort | uniq -c

Erwartet (gekürzt):

{"level":"info","message":"Listening on :7007","service":"rootHttpRouter"}
  13 backend.baseUrl is set to a localhost URL and NODE_ENV is 'production'
   2 Event subscribe request failed with status 404, events backend not fou
   1 Failed to initialize kubernetes backend: valid kubernetes config is mi

Zwei Beobachtungen: Die JSON-Zeilen haben kein Zeitstempel-Feld (den setzt in Kubernetes der Log-Collector), und Backstage warnt jetzt selbst, dass localhost als baseUrl in Produktion kaum stimmen kann. Die Kubernetes-Warnung erscheint nur, wenn dein Block kubernetes: aus Tag 10 fehlt oder der Cluster gelöscht ist.

Sicherheit: Backstage maskiert bekannte Secrets aus der Konfiguration in den Logs („Found 4 new secrets in config that will be redacted”). Das gilt nur für Werte, die per Schema als secret markiert sind – eigene Felder ohne Schema nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 9: Das Docker-Image (nur lesen)

yarn build-image ruft docker build ../.. -f Dockerfile --tag backstage auf. Das Image (Basis node:24-trixie-slim) baust du hier nicht – im Lab fehlt der Platz auf der Docker-Disk. Die Schritte im Überblick:

cd ~/backstage-lab/portal
grep -nE '^(FROM|USER|ENV|COPY|RUN|CMD)' packages/backend/Dockerfile | cut -c1-88
tail -1 .dockerignore

Erwartet:

18:FROM node:24-trixie-slim
22:RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
29:USER node
37:COPY --chown=node:node .yarn ./.yarn
38:COPY --chown=node:node .yarnrc.yml ./
39:COPY --chown=node:node backstage.json ./
42:ENV NODE_ENV=production
47:COPY --chown=node:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz .
48:RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
50:RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000
54:COPY --chown=node:node examples ./examples
57:COPY --chown=node:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./
58:RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
60:CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-conf
*.local.yaml

Der Ablauf ist genau dein Drill 6: Skeleton, Produktionsabhängigkeiten, Bundle, Start mit zwei --config-Dateien. Wichtig: .dockerignore schließt *.local.yaml aus. Im Image fehlen also externalAccess, die Gitea-Integration und der Gitea-Provider – das gehört vor dem ersten Image in app-config.production.yaml, mit allen Secrets als ${…}. Gebaut und gestartet würde es so (nicht live getestet; prod.env wäre eine eigene Datei mit allen Variablen aus pg.env und env.sh):

yarn tsc && yarn build:backend && yarn build-image
docker run -d --name backstage -p 127.0.0.1:7007:7007 \
  --env-file ~/backstage-lab/tag13/prod.env backstage

POSTGRES_HOST muss dann auf die Adresse zeigen, unter der der Container die Datenbank erreicht (z. B. host.docker.internal oder ein gemeinsames Docker-Netz), nicht 127.0.0.1. ENV NODE_ENV=production im Image schaltet JSON-Logs ein und den Guest-Provider ab.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Das Produktions-Backend aus Drill 8 läuft. Die Datei liegt auch unter ~/backstage-lab/code/tag13/kontrolle.sh.

#!/usr/bin/env bash
# kontrolle.sh – Kontrollpunkt Tag 13 (✔/✘). Exit-Code = Anzahl Fehler.
# Erwartet: Produktions-Backend läuft auf :7007, Postgres im Container bs-postgres.
source ~/backstage-lab/setup/env.sh
PG="${PG:-bs-postgres}"
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
  else echo "✘ $1"; fail=$((fail+1)); fi; }
sql() { docker exec "$PG" psql -U backstage -d "$1" -Atc "$2"; }

t "PostgreSQL im Container $PG bereit" \
  "docker exec $PG pg_isready -h 127.0.0.1 -U backstage"
t "Eigene Datenbank für den Katalog" \
  "sql postgres \"select 1 from pg_database where datname='backstage_plugin_catalog'\" \
     | grep -qx 1"
t "Entities liegen in Postgres" \
  "[ \$(sql backstage_plugin_catalog 'select count(*) from final_entities') -gt 0 ]"
t "Suchindex in Postgres (Tabelle documents)" \
  "[ \$(sql backstage_plugin_search 'select count(*) from documents') -gt 0 ]"
t "Backend bereit (readiness)" \
  "curl -sf $BACKSTAGE/.backstage/health/v1/readiness | jq -e '.status == \"ok\"'"
t "Backend liefert das Frontend aus" "curl -sf $BACKSTAGE/ | grep -q '<title>'"
t "Katalog-API liefert User aus Postgres" \
  "bs 'catalog/entities?filter=kind=user' | jq -e 'length > 0'"
t "Kein Klartext-Passwort in app-config.production.yaml" \
  "grep -q 'password: \${POSTGRES_PASSWORD}' $PORTAL/app-config.production.yaml"
exit "$fail"
bash ~/backstage-lab/code/tag13/kontrolle.sh

Erwartet:

✔ PostgreSQL im Container bs-postgres bereit
✔ Eigene Datenbank für den Katalog
✔ Entities liegen in Postgres
✔ Suchindex in Postgres (Tabelle documents)
✔ Backend bereit (readiness)
✔ Backend liefert das Frontend aus
✔ Katalog-API liefert User aus Postgres
✔ Kein Klartext-Passwort in app-config.production.yaml

Danach zurück in den Entwicklungsmodus für Tag 14:

kill $(cat ~/backstage-lab/prod.pid)
~/backstage-lab/setup/portal.sh start

Nach einem Neustart des Rechners zuerst docker start bs-postgres.

Challenge

Sichere die Katalog-Datenbank mit pg_dump, lösche sie und stelle sie aus der Sicherung wieder her. Beweise per SQL, dass alle Entities zurück sind.

Hinweis: Während Backstage läuft, hält es Verbindungen offen – stoppe das Portal vor dropdb, sonst lehnt Postgres das Löschen ab.

Lösung

cd ~/backstage-lab/tag13
sql() { docker exec bs-postgres psql -U backstage -d "$1" -Atc "$2"; }
~/backstage-lab/setup/portal.sh stop
sql backstage_plugin_catalog 'select count(*) from final_entities'
docker exec bs-postgres pg_dump -U backstage -Fc backstage_plugin_catalog \
  > catalog.dump
ls -lh catalog.dump | awk '{print $5, $9}'
docker exec bs-postgres dropdb -U backstage backstage_plugin_catalog
docker exec bs-postgres createdb -U backstage backstage_plugin_catalog
docker exec -i bs-postgres pg_restore -U backstage -d backstage_plugin_catalog \
  < catalog.dump && echo "✔ wiederhergestellt"
sql backstage_plugin_catalog 'select count(*) from final_entities'
~/backstage-lab/setup/portal.sh start

Erwartet (Zahlen hängen von deinem Katalog ab):

✔ gestoppt
15
66K catalog.dump
✔ wiederhergestellt
15
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)

-Fc erzeugt das komprimierte Custom-Format, das pg_restore braucht. Für ein Komplett-Backup aller Plugin-Datenbanken nimmst du pg_dumpall oder sicherst jede backstage_plugin_*-Datenbank einzeln. Ein leerer Katalog wäre übrigens kein Totalverlust – er füllt sich aus Forgejo neu. Verloren wären Scaffolder-Historie, Benachrichtigungen und Benutzereinstellungen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Postgres als verwalteter Dienst (RDS, Cloud SQL, Azure, CloudNativePG im Cluster) mit TLS (PGSSLMODE=require bzw. connection.ssl.ca), Backups mit Point-in-Time-Recovery und eigenem DB-User mit CREATEDB. Darf der User keine Datenbanken anlegen: backend.database.pluginDivisionMode: schema.
  • Secrets aus Vault oder Kubernetes-Secrets als Env-Variablen oder per $file: einbinden. Statt des statischen Lab-Tokens unter backend.auth.externalAccess rotierbare Tokens mit accessRestrictions (z. B. nur Plugin catalog); backend.auth.keys ist veraltet und erzeugt eine Deprecation-Warnung.
  • Kubernetes: das Image aus yarn build-image in der eigenen Registry, Deployment mit livenessProbe/readinessProbe auf die Health-Endpunkte, echte baseUrl hinter Ingress mit TLS. Startpunkt ist das Helm-Chart backstage/backstage aus backstage/charts (nicht live getestet).
  • Mehrere Replikas sind mit Postgres möglich (Scheduler koordiniert Tasks über die DB), TechDocs dann mit publisher.type: awsS3/googleGcs statt lokalem Speicher.
  • Guest-Provider in Produktion abschalten (kein dangerouslyAllowOutsideDevelopment), nur OIDC aus Tag 12; JSON-Logs zentral sammeln.