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 inbundle.tar.gz. Das Pluginapp-backendliefert die App aus – ein Prozess, eine Adresse. - Konfiguration: mehrere
--config-Dateien, später gewinnt; Secrets per${ENV}, Einzelwerte perAPP_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.envErwartet:
# 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-40Erwartet:
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 inpg.envz. B.5433eintragen, 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.yamlErwartet:
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 backstageErwartet:
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.
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/distErwartet (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 -8Erwartet:
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.yamlDrei 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 .
lsErwartet:
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.
- Klicke in der Sidebar auf Settings.
- 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.
- Klicke auf Catalog. Erwartet: der Katalog wie in der Abbildung, ohne die Beispiel-Entities aus create-app.
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 88Erwartet:
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.
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 lengthErwartet (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.pidFortschritt 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 -cErwartet (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
secretmarkiert 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 .dockerignoreErwartet:
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 backstagePOSTGRES_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.shErwartet:
✔ 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 startNach 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 startErwartet (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=requirebzw.connection.ssl.ca), Backups mit Point-in-Time-Recovery und eigenem DB-User mitCREATEDB. 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 unterbackend.auth.externalAccessrotierbare Tokens mitaccessRestrictions(z. B. nur Plugincatalog);backend.auth.keysist veraltet und erzeugt eine Deprecation-Warnung. - Kubernetes: das Image aus
yarn build-imagein der eigenen Registry, Deployment mitlivenessProbe/readinessProbeauf die Health-Endpunkte, echtebaseUrlhinter Ingress mit TLS. Startpunkt ist das Helm-Chartbackstage/backstageausbackstage/charts(nicht live getestet). - Mehrere Replikas sind mit Postgres möglich (Scheduler koordiniert
Tasks über die DB), TechDocs dann mit
publisher.type: awsS3/googleGcsstatt lokalem Speicher. - Guest-Provider in Produktion abschalten (kein
dangerouslyAllowOutsideDevelopment), nur OIDC aus Tag 12; JSON-Logs zentral sammeln.