tibi-docs/src/content/docs/einstieg/neues-projekt.mdx

---
title: Neues Projekt aufsetzen
description: Vom geklonten Starter zum erreichbaren Projekt — inklusive Registrierung und Abnahme.
---

import { Aside, FileTree } from '@astrojs/starlight/components';

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

```sh title="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):

```sh title="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:

```sh title="JWT holen und Projekt registrieren" {7}
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:

```sh title="Projekt-Reload anstoßen"
curl -s -X POST "$CODING_TIBIADMIN_URL/api/_/<PROJECT_NAME>/_/admin/reload" \
  -H "X-Auth-Token: $jwt"
```

<Aside type="caution" title="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.
</Aside>

## 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.

<FileTree>

- api/
  - config.yml
  - hooks/lib/app.server.js
- frontend/src/
  - App.svelte
  - routes/
  - blocks/
  - widgets/

</FileTree>

## 7. Abnahme

```sh title="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)