Doku-Vollausbau: 62 Seiten (Projekt/Admin/Anwender/Referenz), Hook-Referenz mit Signaturen, Corporate-Screenshots, Coverage-Inventar

- Einstieg: Schnellstart + Neues Projekt aus Starter-Skill, Was-ist-Tibi mit Backend/Website-Trennung - Projekt: Sammlungen, Felder, Abfragen, Rechte, Hooks, Dateien, i18n, Suche, SSR, Pagebuilder, Jobs, Audit, Deploy, LLM, MCP - Hook-Referenz: 66 Symbole mit Signatur + Beispiel + Fehlerfall (5 Kapitel) - Admin: Ansichten, Editor, Medien, Exporte, Aktionen, Rechte, KI, Setup, Customizing - Anwender: 11 Anleitungen im professionellen Du-Ton, 30 Corporate-Screenshots - Referenz: Schemas, Token-Köpfe, Fehlerbilder, Shortcuts, OpenAPI-Platzhalter - ADR-0001 bis 0003, Coverage-Skript (282 Items) + Map, Plan-Dateien
2026-10-16 22:49:07 +00:00
1 parent acb1d32355
commit 1897bb50d9
@@ -0,0 +1,131 @@
+---
+title: 'Veröffentlichen'
+description: 'Vom lokalen Stack zu Staging und Live: URLs, Skripte, Reload, Token-Trennung.'
+---
+
+import { Aside, Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+
+Lokal entwickeln, auf Staging prüfen, per Branch auf Live heben.
+Der Weg: `.env`-URLs verstehen, CI-Skripte laufen lassen, Config neu laden, Köpfe sauber trennen.
+Suchbegriffe: Deploy, Staging, Live, Produktion, Reload, Freischaltung.
+
+## URL-Bild
+
+```bash title=".env — die drei Bühnen (Platzhalter im Starter ersetzen)"
+LIVE_URL=https://www                        # Produktion (im echten Projekt: echte Domain)
+STAGING_URL=https://dev-<projekt>.staging.testversion.online
+CODING_URL=https://<projekt>.code.testversion.online
+```
+
+| Bühne | Branch | Was liegt dort |
+|---|---|---|
+| Coding | dein Arbeits-Branch | Deine Sandbox mit Basic-Auth |
+| Staging | `dev` | Prüfbühne, per `ci-staging.sh` gebaut |
+| Live | `master` | Produktion, per `ci-deploy.sh` via rsync |
+
+```text title="Branch zu Bühne: dev wird Staging, master wird Live"
+push auf dev ──▶ CI: validate, build, build:server ──▶ ci-staging.sh ──▶ STAGING_URL
+push auf master ─▶ CI: validate, build, build:server ──▶ ci-deploy.sh ──▶ LIVE_URL
+```
+
+Lokal startest du mit `docker-compose-local.yml` (`tibi`-Profil: fertiges Image, Projekt als `/data` gemountet).
+Staging nutzt `docker-compose-staging.yml` (frisch gebauter Stack im CI-Verzeichnis).
+
+<Aside type="caution">
+Im Starter stehen Platzhalter (`__PROJECT_NAME__`, `_CUSTOMER_ID_`, `LIVE_URL=https://www`).
+Erkennt `ci-deploy.sh` die Vorlage, bricht es ohne Deploy ab — erst alle Platzhalter ersetzen.
+</Aside>
+
+## Deploy-Ablauf
+
+<Tabs>
+<TabItem label="CI-Pipeline (deploy.yml)">
+
+<Steps>
+
+1. Checkout, Starter-Defaults auflösen, `yarn install`.
+2. `yarn validate` (Svelte-Check plus TypeScript) — rot heißt Stopp.
+3. `ci-modify-config.sh` passt die Config für die Zielbühne an.
+4. `yarn build` (Frontend) und `yarn build:server` (SSR-Bundle nach `api/hooks/lib/app.server.js`).
+5. Sourcemaps zu Sentry hochladen.
+6. Branch `dev` → `ci-staging.sh`; Branch `master` → `ci-deploy.sh`.
+
+</Steps>
+
+</TabItem>
+<TabItem label="Staging (ci-staging.sh)">
+
+```bash title="Kurzfassung: kopieren, starten, neu laden"
+rsync -av api frontend/dist frontend/assets "${API_BASEDIR}/"
+docker compose -f docker-compose-staging.yml up -d --build
+curl -X POST "${STAGING_URL}/api/_/admin/reload" \
+  -H "Authorization: Bearer ${ADMIN_TOKEN}" -d '{}'
+curl -X POST "${STAGING_URL}/api/ssr?clear=1" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+</TabItem>
+<TabItem label="Live (ci-deploy.sh)">
+
+```bash title="Kurzfassung: rsync, Rechte, neu laden"
+rsync ... frontend/ "${RSYNC_HOST}":./frontend/   # master: ohne src und *.map
+rsync ... api/      "${RSYNC_HOST}":./api/
+rsync ... media     "${RSYNC_HOST}":./
+curl -X POST "${LIVE_URL}/api/_/admin/reload" -H "Authorization: Bearer ${ADMIN_TOKEN}" -d '{}'
+curl -X POST "${LIVE_URL}/api/ssr?clear=1" -H "Content-Type: application/json" -d '{}'
+```
+
+Zugang per `RSYNC_USER`, `RSYNC_PASS`, `RSYNC_HOST`, `RSYNC_PORT` aus `.env`.
+Auf `master` fliegen Quellen und Karten raus (`--exclude=src --exclude=*.map`).
+
+</TabItem>
+</Tabs>
+
+## Reload-Endpunkte
+
+Nach jedem Deploy: Config neu laden **und** SSR-Cache wischen — sonst siehst du alte Seiten auf neuer Config.
+
+| Endpunkt | Kopf | Wirkung |
+|---|---|---|
+| `POST /api/_/admin/reload` (Live/Staging-URL) | `Authorization: Bearer <ADMIN_TOKEN>` | Projekt-Config über den Reverse-Proxy neu laden |
+| `POST /api/ssr?clear=1` | keiner nötig (`public.post: true`) | Ganzen SSR-Cache löschen |
+| `POST /api/v1/_/:project/_/admin/reload` | `X-Admin-Token` (Server-Ebene) | Gleicher Reload direkt am Server |
+| `POST /api/v1/_/:project/_/admin/regenerate-search` | `X-Admin-Token` | Suchindex neu aufbauen ([Suche](/projekt/suche/)) |
+
+## Token-Trennung
+
+Vier Köpfe, vier Zwecke — aus [Rechte und Tokens](/projekt/rechte-tokens/):
+
+| Kopf | Wert | Wofür hier |
+|---|---|---|
+| `Token` | `ADMIN_TOKEN` | Sammlungs-CRUD in Skripten |
+| `X-Auth-Token` | JWT nach Login | Deine Nutzer-Aktionen beim Testen |
+| `X-Admin-Token` | Server-Admin-Token | Server-Ebene (Projekte, Reload direkt, Backups) — **nicht** ins Deploy-Skript |
+| `Authorization: Bearer …` | `ADMIN_TOKEN` | Proxy-Reload auf Live/Staging — das ist der Deploy-Kopf |
+
+<Aside type="caution">
+`ADMIN_TOKEN` legt **keine** Projekte an und ersetzt kein `X-Admin-Token`.
+Im Deploy-Skript steht er nur hinter `Bearer` für den Proxy-Reload — Projekt-CRUD per JWT läuft getrennt davon.
+</Aside>
+
+## Checkliste und Abnahme
+
+<Steps>
+
+1. Platzhalter in `.env` ersetzt (`PROJECT_NAME`, `PRODUCTION_PATH`, `LIVE_URL`)?
+2. `yarn validate`, `yarn build`, `yarn build:server` lokal grün?
+3. Auf `dev` gepusht, Staging-URL geprüft (anonym, nicht nur mit Token)?
+4. Auf `master` gepusht, Reload plus `?clear=1` in den CI-Logs gesehen?
+5. Live-URL anonym geöffnet: Navigation da, Bilder da, kein alter Stand?
+
+</Steps>
+
+| Fehlerbild | Ursache | Lösung |
+|---|---|---|
+| Deploy bricht mit „starter template detected“ ab | Platzhalter noch drin | `.env` und `PRODUCTION_PATH` vervollständigen |
+| Neue Config wirkt nicht | Reload vergessen | Reload-Endpunkt pro Bühne aufrufen |
+| Alte Seite trotz neuer Daten | SSR-Cache alt | `?clear=1`, Köpfe `X-SSR-Cache`/`X-SSR-Cleared` prüfen |
+| `project not found` | Namespace falsch | [Neues Projekt](/einstieg/neues-projekt/) Schritt 5 |
+| 401/403 beim Reload | Falscher Kopf (z. B. `Token:` statt `Bearer`) | Tabelle oben: Deploy nimmt `Bearer`, Server-API nimmt `X-Admin-Token` |
+
+Verifiziert am e3f92eb 2026-10-14 (tibi-svelte-starter, .env, ci-deploy.sh, ci-staging.sh, deploy.yml).