cms/tibi-svelte-starter
Template
3
0
Fork 2
Code Issues Pull Requests Projects Releases Wiki Activity

✨ feat: update deployment scripts and configuration; enhance CI/CD process with new scripts for staging and production

Browse Source
This commit is contained in:
Sebastian Frank
2026-02-26 12:36:53 +00:00
parent 965a505e15
commit 5707eb30dd
9 changed files with 364 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
README.md
View File

@@ -2,87 +2,170 @@
Starter Kit für SPAs(s) `;)` mit Svelte und TibiCMS inkl. SSR
## Neues Projekt starten
## Neues Projekt erstellen — Schritt-für-Schritt
Nachdem du dieses Repository als Vorlage geklont hast, passe die Platzhalter an dein Projekt an:
Diese Anleitung ist so geschrieben, dass ein autonomer Agent oder ein Entwickler sie 1:1 abarbeiten kann, um ein eigenständiges tibi-Projekt mit eigener Code-Server-Subdomain zu erstellen.
1. **`.env`**: Ersetze `__PROJECT_NAME__` mit deinem Projektnamen (z.B. `mein-projekt`).
Die folgenden URLs werden automatisch abgeleitet:
- `CODING_URL=https://mein-projekt.code.testversion.online`
- `STAGING_URL=https://dev-mein-projekt.staging.testversion.online`
2. **`frontend/spa.html`** / **`api/templates/spa.html`**: Ersetze `__PROJECT_TITLE__` mit dem Seitentitel.
3. **`api/config.yml.env`**: Passe `ADMIN_TOKEN`, Datenbank-Name und weitere Secrets an.
4. **`docker-compose-local.yml`**: Suche nach `project_name__` und ersetze mit deinem Projektnamen (Container-Benennung).
5. **Demo-Inhalte entfernen**: Die Demo-Seite besteht aus diesen Dateien, die für ein echtes Projekt entfernt/ersetzt werden können:
- `frontend/src/blocks/` — Block-Komponenten (HeroBlock, FeaturesBlock, RichtextBlock, AccordionBlock, ContactFormBlock, BlockRenderer, NotFound)
- `frontend/mocking/content.json` — Demo-Mockdaten für Content
- `frontend/mocking/navigation.json` — Demo-Mockdaten für Navigation
- `api/collections/content.yml` — Content-Collection-Konfiguration
- `api/collections/navigation.yml` — Navigation-Collection-Konfiguration
- `tests/e2e/demo.spec.ts` — Demo-E2E-Tests
- `video-tours/tours/demo-showcase.tour.ts` — Demo-Video-Tour
6. **`frontend/src/App.svelte`**: Passe Header, Footer und Content-Loading an dein Datenmodell an.
### Voraussetzungen
- Zugang zum Code-Server unter `*.code.testversion.online`
- `git`, `yarn`, `make`, `docker compose` verfügbar
- Traefik-Reverse-Proxy läuft auf dem Host (verwaltet `*.code.testversion.online`-Subdomains automatisch via Docker-Labels)
### 1. Repository klonen (falls noch nicht geschehen)
Wenn du bereits in einem geklonten Projekt arbeitest, überspringe diesen Schritt und gehe direkt zu **Schritt 2**.
```sh
# Platzhalter ersetzen (Beispiel für Linux/Mac):
sed -i 's/__PROJECT_NAME__/mein-projekt/g' .env
sed -i 's/__PROJECT_TITLE__/Mein Projekt/g' frontend/spa.html api/templates/spa.html
# Im Workspace-Verzeichnis (z.B. /WM_Dev/src/gitbase.de/cms/)
git clone https://gitbase.de/cms/tibi-svelte-starter.git mein-projekt
cd mein-projekt
git remote rename origin template
# Neues Remote-Repo anlegen (z.B. auf gitbase.de) und als origin setzen:
# git remote add origin https://gitbase.de/org/mein-projekt.git
```
## Wozu?
### 2. Platzhalter ersetzen
Via Svelte wird eine SPA (Single-Page-App) programmiert. Dazu wird der Code einmal für den Browser aufgebreitet und außerdem für den Server kompiliert und transpiliert. Der Server-Code wird in einem tibi-server SSR-Hook (server side rendering) eingebunden und generiert dort fertiges HTML anhand der aktuelle Route für SEO und optimierte Ladezeiten.
Alle Platzhalter müssen durch die echten Projektwerte ersetzt werden. Hier die vollständige Liste:
Die Navigation innerhalb der APP im Browser löst dagegen nur API-Aufrufe aus ohne jedesmal einen SSR-Prozess anzustoßen.
Um die SSR-Last so gering wie möglich zu halten, wurde ein Caching in der "ssr"-Collection der API implementiert.
## Toolchain
### git
nach `git clone ...`
| Platzhalter | Wo | Ersetzen durch | Beispiel |
| --- | --- | --- | --- |
| `__PROJECT_NAME__` | `.env` | Projektname (kebab-case, wird für URLs und Container verwendet) | `mein-projekt` |
| `__TIBI_NAMESPACE__` | `.env` | Tibi-Namespace (snake_case, wird als DB-Prefix und in API-URLs verwendet) | `mein_projekt` |
| `__NAMESPACE__` | `api/config.yml`, `frontend/.htaccess` | Gleicher Wert wie `TIBI_NAMESPACE` | `mein_projekt` |
```sh
git lfs install
git lfs pull
# Projektname (kebab-case) — für URLs, Docker-Container, Subdomains
PROJECT=mein-projekt
# Tibi-Namespace (snake_case) — für DB, API-Pfade
NAMESPACE=mein_projekt
sed -i "s/__PROJECT_NAME__/$PROJECT/g" .env
sed -i "s/__TIBI_NAMESPACE__/$NAMESPACE/g" .env
sed -i "s/__NAMESPACE__/$NAMESPACE/g" api/config.yml frontend/.htaccess
```
### Abhängigkeiten laden
**Ergebnis in `.env`:**
```dotenv
PROJECT_NAME=mein-projekt
TIBI_NAMESPACE=mein_projekt
CODING_URL=https://mein-projekt.code.testversion.online
STAGING_URL=https://dev-mein-projekt.staging.testversion.online
```
### 3. Seitentitel anpassen
Der Seitentitel wird dynamisch über `<svelte:head>` in `frontend/src/App.svelte` gesetzt. Die Demo-App verwendet dafür die Konstante `SITE_NAME`. In einem neuen Projekt wird `App.svelte` typischerweise komplett neu geschrieben — dabei einfach sicherstellen, dass `<svelte:head>` mit einem passenden `<title>` vorhanden ist. SSR injiziert ihn dann automatisch über den `<!--HEAD-->`-Platzhalter in `spa.html`.
### 4. Admin-Token prüfen
`api/config.yml.env` enthält bereits ein `ADMIN_TOKEN`. Für Produktionsprojekte durch ein sicheres Token ersetzen:
```sh
echo "ADMIN_TOKEN=$(openssl rand -hex 20)" > api/config.yml.env
```
### 5. Subdomains prüfen
Traefik erkennt die Docker-Labels automatisch. Nach `make docker-up` sind folgende URLs verfügbar:
| Dienst | URL |
| --- | --- |
| Website (BrowserSync) | `https://{PROJECT_NAME}.code.testversion.online/` |
| Tibi Admin | `https://{PROJECT_NAME}-tibiadmin.code.testversion.online/` |
| Tibi Server API | `https://{PROJECT_NAME}-tibiserver.code.testversion.online/` |
| Maildev | `https://{PROJECT_NAME}-maildev.code.testversion.online/` |
**Es ist KEINE manuelle Traefik-Konfiguration nötig.** Die Subdomains werden automatisch über das Docker-Label `online.testversion.code.subdomain=${PROJECT_NAME}` registriert. Traefik überwacht Docker-Events und erstellt die Routen dynamisch.
### 6. Starten
```sh
yarn install
```
### Entwickeln auf dem Code-Server mit Docker Compose Stack
```sh
make docker-start
make docker-up # Stack im Hintergrund starten
# oder
make docker-up
make docker-down
# "make help" zeigt alle Kommandos
make docker-start # Stack im Vordergrund (CTRL-C zum Stoppen)
```
| UI | URL |
| --- | --- |
| Website | <https://tibi-svelte-starter.code.testversion.online/> |
| Tibi Admin | <https://tibi-svelte-starter-tibiadmin.code.testversion.online/> |
| Maildev | <https://tibi-svelte-starter-maildev.code.testversion.online/> |
### Bauen
Prüfe, ob alles läuft:
```sh
# moderne Browser
yarn build
# alte Browser (IE11)
yarn build:legacy
# serverseitiges Rendering
yarn build:server
# Admin-Module
yarn build:admin
make docker-ps # Container-Status anzeigen
make docker-logs # Logs verfolgen
```
### 7. Mock-Modus (Frontend ohne tibi-server)
Für schnelle UI-Entwicklung ohne Backend:
```sh
# In .env setzen:
MOCK=1
# Dann:
make docker-up
```
Mock-Daten liegen in `frontend/mocking/` als JSON-Dateien. Fehlende Endpunkte liefern 404.
### 8. Demo-Inhalte entfernen
Für ein echtes Projekt die Demo-Dateien entfernen/ersetzen:
| Datei/Ordner | Inhalt |
| --- | --- |
| `frontend/src/blocks/` | Demo-Block-Komponenten (HeroBlock, FeaturesBlock, etc.) |
| `frontend/mocking/content.json` | Demo-Mockdaten für Content |
| `frontend/mocking/navigation.json` | Demo-Mockdaten für Navigation |
| `api/collections/content.yml` | Content-Collection-Konfiguration |
| `api/collections/navigation.yml` | Navigation-Collection-Konfiguration |
| `tests/e2e/` | Demo-E2E-Tests |
| `video-tours/tours/` | Demo-Video-Tour |
Danach `frontend/src/App.svelte` (Header, Footer, Content-Loading) an das eigene Datenmodell anpassen.
### 9. Build und Deployment
```sh
yarn build # Frontend für moderne Browser
yarn build:server # SSR-Bundle (für tibi-server goja-Hooks)
yarn build:admin # Admin-Module (optional)
yarn validate # TypeScript + Svelte prüfen (muss 0 Fehler/Warnungen zeigen)
```
### Checkliste für autonome Agents
```text
[ ] Repository geklont und Remote gesetzt
[ ] __PROJECT_NAME__ in .env ersetzt
[ ] __TIBI_NAMESPACE__ in .env ersetzt
[ ] __NAMESPACE__ in api/config.yml und frontend/.htaccess ersetzt
[ ] App.svelte mit eigenem Template und <svelte:head> (inkl. <title>) erstellt
[ ] ADMIN_TOKEN in api/config.yml.env gesetzt
[ ] yarn install ausgeführt
[ ] make docker-up gestartet
[ ] Website unter https://{PROJECT_NAME}.code.testversion.online/ erreichbar
[ ] yarn validate zeigt 0 Fehler und 0 Warnungen
[ ] yarn build und yarn build:server erfolgreich
```
---
## Architektur
Via Svelte wird eine SPA (Single-Page-App) programmiert. Der Code wird einmal für den Browser aufbereitet und außerdem für den Server kompiliert und transpiliert. Der Server-Code wird in einem tibi-server SSR-Hook eingebunden und generiert fertiges HTML anhand der aktuellen Route — für SEO und optimierte Ladezeiten.
Die Navigation innerhalb der App löst nur API-Aufrufe aus, ohne jedes Mal SSR anzustoßen. Ein Cache in der `ssr`-Collection minimiert die SSR-Last.
**SSR-Details:**
- `<title>` und `<meta description>` kommen über `<svelte:head>` aus `App.svelte` → SSR injiziert sie in den `<!--HEAD-->`-Platzhalter von `spa.html`
- `<html lang>` wird vom SSR-Hook (`api/hooks/ssr/get_read.js`) anhand der URL-Sprache gesetzt
- SSR-Bundle wird mit `yarn build:server` erstellt und landet in `api/hooks/lib/app.server.js`
**Weiteres Build-Target:**
```sh
yarn build:admin # Admin-Module
```