Search by

steilaufwaerts / kirby-boilerplate

steilaufwaerts

Kirby-5-Boilerplate von STEILAUFWAERTS

Package info

gitlab.com/steilaufwaerts/kirby-boilerplate

Issues

Type:project

pkg:composer/steilaufwaerts/kirby-boilerplate

Statistics

Installs: 14

Dependents: 0

Suggesters: 0

Stars: 0

1.1.3 2024-03-27 11:16 UTC

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.

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-org 5 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

  1. Boilerplate ohne Git-Historie kopieren, im neuen Ordner git init.
  2. In composer.json und package.json den Namen anpassen.
  3. Abhängigkeiten installieren: composer install, npm install.
  4. site/config/secrets.example.php nach site/config/secrets.php kopieren, 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)
    
  5. ./dev.sh starten, http://localhost:8000/panel öffnen und den ersten Benutzer anlegen.

  6. Im Panel pflegen: Unternehmen, Menüs, Formulare (Absender, Empfänger), Favicons, SEO (inkl. Social-Media-Profile und globales OG-Image).
  7. Optik anpassen: Tokens in src/css/tokens/ (Farben, Schriften, Abstände, Container, Grid), danach Header, Footer und Bausteine.
  8. Demo-Inhalte der Startseite (content/home/) und das Beispielbild durch echte Inhalte ersetzen, Impressum und Datenschutz befüllen.

Befehle

BefehlZweck
./dev.shPHP-Server (Port 8000) und Vite-Dev-Server (Port 5173)
npm run buildBuild nach public/assets
php -l <datei>PHP-Syntax prüfen
composer outdated, npm outdatedveraltete 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>, Passwort staw-dev.
  • .htpasswd im Projekt-Root erzeugen (steht in .gitignore):

    htpasswd -nbB staw-<kunde> staw-dev > .htpasswd
    
  • AuthUserFile in der .htaccess auf 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)

  1. Dokumentstamm auf das Projekt-Root setzen; die Root-.htaccess leitet intern nach public/ weiter, public/index.php sorgt für jede Domain dafür, dass /public nicht in den Links auftaucht. Alternativ den Dokumentstamm direkt auf public/ setzen.
  2. PHP-Version 8.4: Die Root-.htaccess setzt den Handler php-fastcgi8.4; bei anderer Version anpassen.
  3. Auf dem Server composer install --no-dev ausführen und npm run build lokal oder dort, public/assets muss vorhanden sein.
  4. site/config/secrets.php auf dem Server anlegen (nicht im Repo).
  5. Host-Config site/config/config.<domain>.php für die Umgebung, siehe docs/extending.md.
  6. 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, mit backup.json darin. 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-.htaccess entfernen.
  • 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-backup eingerichtet 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):

  1. composer outdated und npm outdated prüfen.
  2. Bei Major-Updates zuerst Changelog bzw. Migrations-Guide lesen (Kirby, Vite, Tailwind, Plugins).
  3. Aktualisieren, dann npm run build, PHP-Syntax prüfen, alle Seiten rendern, Panel öffnen, Kontaktformular absenden.
  4. 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.