steilaufwaerts / kirby-boilerplate
Kirby-5-Boilerplate von STEILAUFWAERTS
Package info
gitlab.com/steilaufwaerts/kirby-boilerplate
Type:project
pkg:composer/steilaufwaerts/kirby-boilerplate
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0
- getkirby/cms: ^4.1
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Fundament für Kirby-Projekte von STEILAUFWAERTS: gleicher Techstack, gleiche Ordnerstruktur, gleiche Namensregeln. Für ein neues Projekt kopieren und optisch ans Screendesign anpassen.
- Regeln: docs/conventions.md
- Erweiterungen (Seitentyp, Section, Formular, Font …): docs/extending.md
Enthalten
Kirby 5 mit Public-Folder-Setup, Vite und Tailwind CSS, kirby-seo mit Schema.org, imagex, Retour, Uniform. Layout mit Header, Navigation und Footer, Bild-, Video-, Medien-, Button-, Headline- und Rich-Text-Baustein, Text-, Bild- und Video-Block, Kontaktformular mit Mails, Favicons und Web-App-Manifest, OG-Image-Fallback, Inhaltssicherung im Panel (Versionen, Papierkorb, Vollbackup, siehe Inhalte sichern) und die Rolle „Redakteur“. Die Startseite zeigt jeden Baustein einmal.
Voraussetzungen
- PHP 8.4 oder 8.5 (
spatie/schema-org5 braucht 8.4+) - Composer, Node.js ab 20.19 bzw. 22.12, npm
Ist global eine ältere PHP-Version verlinkt, sucht dev.sh selbst eine passende (Homebrew php@8.5/php@8.4, oder per PHP_BIN). Composer dann mit derselben Version aufrufen:
/opt/homebrew/opt/php@8.5/bin/php "$(which composer)" install
Neues Projekt starten
- Boilerplate ohne Git-Historie kopieren, im neuen Ordner
git init. - In
composer.jsonundpackage.jsonden Namen anpassen. - Abhängigkeiten installieren:
composer install,npm install. site/config/secrets.example.phpnachsite/config/secrets.phpkopieren, SMTP-Daten eintragen und neue Zufallswerte erzeugen:php -r "echo base64_encode(random_bytes(32));" # uniform.honeytime.key php -r "echo bin2hex(random_bytes(32));" # content.salt und cookie.key (je einmal)./dev.shstarten,http://localhost:8000/panelöffnen und den ersten Benutzer anlegen.- Im Panel pflegen: Unternehmen, Menüs, Formulare (Absender, Empfänger), Favicons, SEO (inkl. Social-Media-Profile und globales OG-Image).
- Optik anpassen: Tokens in
src/css/tokens/(Farben, Schriften, Abstände, Container, Grid), danach Header, Footer und Bausteine. - Demo-Inhalte der Startseite (
content/home/) und das Beispielbild durch echte Inhalte ersetzen, Impressum und Datenschutz befüllen.
Befehle
| Befehl | Zweck |
|---|---|
./dev.sh | PHP-Server (Port 8000) und Vite-Dev-Server (Port 5173) |
npm run build | Build nach public/assets |
php -l <datei> | PHP-Syntax prüfen |
composer outdated, npm outdated | veraltete Pakete anzeigen |
Passwortschutz (Entwicklung, Staging)
Die Root-.htaccess schützt die Seite per Basic Auth; aus dem Büro (109.90.127.165, 109.90.127.166) ohne Abfrage.
- Konvention: Nutzer
staw-<kunde>, Passwortstaw-dev. .htpasswdim Projekt-Root erzeugen (steht in.gitignore):htpasswd -nbB staw-<kunde> staw-dev > .htpasswdAuthUserFilein der.htaccessauf den absoluten Serverpfad setzen (Plesk: Dateimanager →.htpasswd→ Eigenschaften). Ein falscher Pfad führt zu Fehler 500.- Hinter einem Proxy oder CDN sieht der Server nicht die echte Besucher-IP, dann greift die Büro-Freigabe nicht.
Deploy (Plesk)
- Dokumentstamm auf das Projekt-Root setzen; die Root-
.htaccessleitet intern nachpublic/weiter,public/index.phpsorgt für jede Domain dafür, dass/publicnicht in den Links auftaucht. Alternativ den Dokumentstamm direkt aufpublic/setzen. - PHP-Version 8.4: Die Root-
.htaccesssetzt den Handlerphp-fastcgi8.4; bei anderer Version anpassen. - Auf dem Server
composer install --no-devausführen undnpm run buildlokal oder dort,public/assetsmuss vorhanden sein. site/config/secrets.phpauf dem Server anlegen (nicht im Repo).- Host-Config
site/config/config.<domain>.phpfür die Umgebung, siehe docs/extending.md. - Cron für das Vollbackup der Inhalte einrichten, siehe Inhalte sichern.
Inhalte sichern
Das Plugin site/plugins/content-backup sichert vor jeder Änderung im Panel den alten Stand, protokolliert wer wann was geändert hat und legt gelöschte Seiten und Dateien in einen Papierkorb. Alles liegt in content-backups/ neben content/ (nicht im Repo, nicht öffentlich). Ausführliche Doku mit Rechten, Optionen und Anleitung zur Weitergabe: docs/content-backup-plan.md.
- Versionen: Button „Versionen“ oben an jeder Seite und an der Site. Zeigt alle gesicherten Stände, den Vergleich mit dem aktuellen Inhalt (bei Dateien alt/neu mit Vorschau) und stellt einen Stand wieder her. Wiederherstellen sichert den aktuellen Stand vorher, ist also selbst umkehrbar. Felder, die es im Blueprint nicht mehr gibt, werden angezeigt, aber nicht zurückgeschrieben.
- Sicherungen (eigener Eintrag in der Panel-Seitenleiste): Status des letzten Vollbackups, Downloads der Zips, Papierkorb-Status und den letzten 20 Änderungen.
- Papierkorb: über den Button in „Sicherungen“; einzelne Einträge wiederherstellen oder alles nach Bestätigung endgültig leeren.
- Vollbackup: Zip von
content/, Name<projekt>_content_<datum>_<auslöser>.zip, mitbackup.jsondarin. Auf dem Server bleiben die neuesten drei.
Cron in Plesk („Geplante Aufgaben“ → PHP-Skript ausführen bzw. Befehl, täglich nachts):
php site/plugins/content-backup/bin/backup.php
Ein Zip entsteht nur, wenn sich in content/ seit dem letzten etwas geändert hat; sonst meldet der Cron „kein neues Zip“ (--force erzwingt eins, Option skipUnchanged). Fehlt der Cron oder fällt er aus, prüft der nächste Panel-Aufruf nach 26 Stunden und legt bei Änderungen ein Backup an. Das ist nur eine Absicherung: Unter PHP-FPM läuft es nach der Antwort, sonst wartet dieser eine Aufruf auf das Zip. Optionen (Aufbewahrung, Schwellen für die Papierkorb-Empfehlung, Zeitzone) stehen im Kopf von site/plugins/content-backup/index.php. Rechte je Rolle: Admins dürfen alles, Redakteure (site/blueprints/users/editor.yml) sehen alles ein, stellen aber nichts wieder her und löschen nichts; freigegeben wird im Rollen-Blueprint unter permissions: site.content-backup. Alles liegt auf demselben Server; gegen einen Serverausfall helfen nur die Backups des Hosters.
Vor dem Livegang
- Passwortschutz aus der Root-
.htaccessentfernen. - Host-Config der Live-Domain mit
url; Robots dort nicht sperren. - Kirby-Lizenz und kirby-seo-Lizenz kaufen und im Panel aktivieren (beide nur für die Live-Domain nötig).
- SMTP-Versand mit echtem Formular testen, Absender-Adresse passt zum SMTP-Konto.
- Favicons, globales OG-Image und Social-Media-Profile gepflegt.
- Cron für
content-backupeingerichtet und einmal von Hand ausgeführt; unter „Sicherungen“ steht ein aktuelles Vollbackup.
Wartung
Die Boilerplate wird laufend aktualisiert. Update-Routine (als Claude-Skill update-dependencies ausführbar):
composer outdatedundnpm outdatedprüfen.- Bei Major-Updates zuerst Changelog bzw. Migrations-Guide lesen (Kirby, Vite, Tailwind, Plugins).
- Aktualisieren, dann
npm run build, PHP-Syntax prüfen, alle Seiten rendern, Panel öffnen, Kontaktformular absenden. - Geänderte Versionen in CHANGELOG.md festhalten.
Abhängig von Vite ist im eigenen Plugin site/plugins/vite nur der Manifest-Pfad (.vite/manifest.json samt Aufbau) und der Dev-Client (/@vite/client). Bei Vite-Major-Updates genau diese beiden Punkte im Changelog prüfen und im Plugin-Kopf die zuletzt geprüfte Version aktualisieren.
Blockiert Composer ein Update wegen eines Sicherheitshinweises in einer Abhängigkeit, die ein Paket fest vorgibt, den Hinweis nur vorübergehend und mit Begründung unter config.audit.ignore in composer.json freigeben und mit dem nächsten Update wieder entfernen.