Neues Projekt aufsetzen

Anleitung für Projekt-Entwickler: du klonst tibi-svelte-starter und baust daraus eine eigenständige Website auf Tibi-Basis — normale kleine Websites, Shops, Intranet-Anwendungen usw. Das Verwaltungs-Backend (Tibi-Server + tibi-admin) entwickelst du nicht weiter, du nutzt es.

Verifiziert gegen: Starter-README.md, Skill tibi-project-setup/SKILL.md, Makefile, docker-compose-local.yml, api/config.yml. Stand: am Code geprüft, nicht aus Alt-Doku.

Setup-Checkliste

• Geklont, origin zeigt aufs Projekt-Repo (template heißt das Starter-Remote)
• __PROJECT_NAME__ (kebab-case) und __TIBI_NAMESPACE__ (snake_case) ersetzt
• __ORG__ / __PROJECT__ ersetzt, kein __*__ mehr per rg findbar
• .env-URLs gesetzt (CODING_URL, CODING_TIBIADMIN_URL, STAGING_URL, LIVE_URL)
• api/config.yml.env mit frischem ADMIN_TOKEN + ADMIN_ASSET_VERSION
• App.svelte hat <svelte:head> mit <title>
• yarn install, make docker-up, Website + Admin + API antworten
• yarn validate, yarn build, yarn build:server fehlerfrei

1. Klonen und Remotes

Platzhalter prüfen

git clone https://gitbase.de/cms/tibi-svelte-starter.git mein-projekt
cd mein-projekt
git remote rename origin template
git remote add origin https://gitbase.de/<org>/<repo>.git

2. Platzhalter und Starter-Reste

Ersetzen in .env, api/config.yml, api/hooks/config-client.js, package.json, README.md und frontend/.htaccess (falls Apache-Rewrite genutzt wird):

Platzhalter ersetzen

rg '__[A-Z0-9_]+__' . --glob '*.{yml,js,env,htaccess,json,md,ts,svelte}'

package.json darf danach nicht mehr aufs Starter-Repo zeigen. PRODUCTION_PATH, SENTRY_PROJECT und TIBI_NAMESPACE projektspezifisch setzen.

3. Welcher Betriebs-Pfad?

Pfad A — lokaler Starter-Stack (Standard): make docker-up startet docker-compose-local.yml mit Profil tibi. Das Projekt wird als /data in tibiserver gemountet, DB_DIAL, DB_PREFIX, MAIL_HOST kommen aus Container-Env. Traefik-URLs:

• Website: https://<projekt>.code.testversion.online/
• Admin: https://<projekt>-tibiadmin.code.testversion.online/
• Roh-Server: https://<projekt>-tibiserver.code.testversion.online/ (falls Profil aktiv)
• Maildev: https://<projekt>-maildev.code.testversion.online/

Pfad B — geteilter/fremder tibi-server: nur wenn die Umgebung das ausdrücklich verlangt (eigene Server-Config, explizite Projekt-Registrierung). Dann vorab klären: welches Admin-Token für /api/v1/project, welche Basis-URL, wie der Projektpfad gemountet ist. Keine Pfad-B-Schritte im lokalen Starter-Stack erfinden.

4. Dateien sind nicht gleich registriert

Dateien auf Platte definieren das Projekt. Erst die Registrierung macht es dem laufenden tibi-server bekannt. Bis dahin antwortet der Namespace mit project not found — das ist dann kein Proxy-Fehler.

5. Registrieren (wenn project not found)

Im lokalen Standard-Setup per admin / admin einloggen und JWT nutzen — der Admin-Host leitet /api an den tibi-server weiter, ein eigener Roh-Server-Host ist nicht nötig:

JWT holen und Projekt registrieren

jwt=$(curl -s -X POST "$CODING_TIBIADMIN_URL/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

curl -s -X POST "$CODING_TIBIADMIN_URL/api/project" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $jwt" \
  -d '{"name":"<PROJECT_NAME>","description":"...","configFile":"/data/api/config.yml","enabled":true}'

Danach erscheint das Projekt unter GET /api/v1/project am Server (über den Admin-Proxy: GET /api/project), und /_/<namespace>/... löst auf. Nach Config-Änderungen neu laden:

Projekt-Reload anstoßen

curl -s -X POST "$CODING_TIBIADMIN_URL/api/_/<PROJECT_NAME>/_/admin/reload" \
  -H "X-Auth-Token: $jwt"

Token nicht verwechseln

Verwechsle ADMIN_TOKEN aus api/config.yml.env nicht mit System-Rechten: er schreibt Sammlungen (Kopf Token), registriert aber keine Projekte. Deploy-Skripte nutzen ihn separat als Authorization: Bearer auf dem Projekt-Reload.

6. Inhalte und URLs verstehen

• api/config.yml definiert namespace, collections (Inhalte, Medien, Navigation, Tags, Kommentare, SSR-Cache), assets (dist, fonts, img) und admin.tokens.
• Frontend: Svelte-SPA in frontend/src/ (App.svelte, routes/, blocks/, widgets/). yarn build baut Browser-Bundle plus Admin-Modul, yarn build:server das SSR-Bundle für api/hooks/lib/app.server.js.
• Medien-URLs folgen /api/medialib/<entryId>/file/<name>?filter=..., gerendert nur über MedialibImage.
• Öffentliche Abfragen brauchen active:true — auch bei Navigation und Medien, sonst bleibt die Navigation leer, obwohl Lesen mit Token klappt.

• Ordnerapi/

  • config.yml
  • hooks/lib/app.server.js
• Ordnerfrontend/src/

  • App.svelte
  • Ordnerroutes/

    • …
  • Ordnerblocks/

    • …
  • Ordnerwidgets/

    • …

7. Abnahme

Abnahme: Build und Erreichbarkeit

yarn validate
yarn build
yarn build:server
curl -I "$CODING_URL"
curl -I "$CODING_TIBIADMIN_URL"

Anonyme SSR-Seite prüfen (Navigation vorhanden, Bilder mit _lookup), nicht nur Lesen mit Token. Erst dann ist das Projekt wirklich aufgesetzt.

Verifiziert am e3f92eb 2026-10-17 (tibi-svelte-starter), am 68b4278 2026-10-17 (tibi-server)