Installation

WebBlocks CMS unterstützt einen Paket-Consumer-Installationsablauf für frische Laravel-Anwendungen, einen browserbasierten Installationsassistenten für frische Wartungs-Repo-Installationen und einen manuellen Laravel-CLI-Installationsweg.

Beginnen Sie eine Neuinstallation damit, den WebBlocks-CMS-Quellcode auf Ihren Rechner zu holen. Führen Sie Composer aus, erstellen Sie .env, verwenden Sie Artisan und öffnen Sie den Browser-Installationsassistenten erst, nachdem der Quellcode lokal vorhanden ist.

Eine Installation gilt als abgeschlossen, wenn die Anwendung über eine funktionierende CMS-Basis verfügt:

• ein App-Key existiert
• die Datenbank ist erreichbar
• die erforderlichen Tabellen existieren
• die Kern-Seed-Daten existieren
• der erste aktive super_admin existiert
• eine Abschlussmarkierung der Installation ist in system_settings gespeichert

Bevor Sie Installationsbefehle ausführen, stellen Sie sicher, dass das WebBlocks-CMS-Repository lokal vorhanden ist.

In ein neues Verzeichnis klonen:

In ein bereits angelegtes leeres Verzeichnis klonen:

Sobald der Quellcode lokal vorhanden ist, fahren Sie mit einem der unten beschriebenen Neuinstallationswege fort.

WebBlocks-CMS-Installationen sind ausschließlich Update-Konsumenten. Sie dürfen CMS-Updates abrufen, ziehen oder herunterladen, aber keine Commits oder Tags in das kanonische CMS-Upstream-Repository zurückschieben. Führen Sie für bestehende lokale Installations-Klone einmalig git remote set-url --push origin DISABLED in der Arbeitskopie der Installation aus.

Verwenden Sie diesen Ablauf, wenn WebBlocks CMS über Composer in eine frische Laravel-Anwendung installiert wird.

Unterstützte Optionen:

• --name= Anzeigename des ersten Super-Admins
• --email= E-Mail-Adresse des ersten Super-Admins
• --password= Passwort des ersten Super-Admins
• --site-name= Name der Standard-Site
• --site-handle= Handle der Standard-Site
• --repair-partial benennt leere partielle CMS-Tabellen vor den Neuinstallations-Migrationen um
• --force überschreibt bei Bedarf paketeigene CMS-Assets oder veröffentlichte Konfigurationsdateien

Was webblocks:install tut:

• veröffentlicht config/webblocks-cms.php, wenn die Host-App sie noch nicht hat
• entfernt die unveränderte Laravel-Willkommensroute aus routes/web.php, wenn dies sicher ist, mit einem zeitgestempelten Backup zuerst, damit öffentliche CMS-Routen / bedienen können
• patcht app/Models/User.php mit WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
• erstellt ein zeitgestempeltes Backup, bevor User.php geändert wird
• überspringt das Patchen, wenn das Trait bereits vorhanden ist
• schlägt mit einer klaren Meldung fehl, wenn User.php keine erkennbare App\Models\User extends Authenticatable-Klasse ist
• führt den Neuinstallations-Migrationspfad des Pakets für saubere Consumer-Installationen aus
• erkennt partielle CMS-Schemata vor dem Ausführen der Neuinstallations-Migrationen und meldet vorhandene CMS-Tabellen, Zeilenanzahlen, zugehörige Migrationszeilen und bekannte Fremdschlüsselkonflikte
• repariert leere partielle CMS-Schemata nur, wenn --repair-partial angegeben ist, indem leere CMS-Tabellen vor dem Fortfahren mit einem zeitgestempelten _before_cms_install_...-Suffix umbenannt werden
• verweigert die automatische Reparatur, wenn eine partielle CMS-Tabelle Zeilen enthält
• überspringt das erneute Ausführen des frischen Schemas, wenn bereits CMS-Tabellen existieren
• erstellt Laravel-Unterstützungstabellen, ohne Migrationen der Host-Anwendung auszuführen; derzeit umfasst dies CMS-Passwort-Reset-Tokens sowie sessions, cache und cache_locks, wenn diese datenbankgestützten Treiber konfiguriert sind
• führt das normale Laravel-Migrationsset der Host-Anwendung nicht als Teil der Paketinstallation aus und vermeidet so Konflikte mit der bereits erstellten CMS-kompatiblen users-Tabelle
• bereitet das Stammverzeichnis der backups-Dateisystem-Disk vor, die von Backup / Restore verwendet wird
• installiert paketeigene CMS-Assets nach public/cms
• erstellt public/storage, wenn es fehlt und die Umgebung es erlaubt
• seedet Sprachen (Locales), Sites, Slot-Typen, Seitenlayouts, Icons und Kern-Blocktypen idempotent
• speichert die installierte Version und die Abschlussmarkierung der Installation in system_settings
• erstellt den ersten aktiven super_admin nur, wenn noch keiner existiert

Die Paket-Authentifizierung ist Laravel-nativ und erfordert weder Breeze, Jetstream, Laravel UI noch Fortify. Melden Sie sich nach der Installation unter /webadmin/login an, wenn die Auth-Routen des CMS-Pakets aktiv sind. CMS-eigene Auth-Views und Admin-Gast-Weiterleitungen verwenden Paket-Routennamen wie webblocks.auth.login und webblocks.auth.logout, sodass ein Host-Produkt seine eigene globale login-Route, zum Beispiel /quiztem/login, behalten kann, ohne CMS-Formularaktionen oder /webadmin-Weiterleitungen zu übernehmen.

Für die aktuelle v1.32.x-Paket-Consumer-Grenze bleibt App\Models\User der Host-Anwendung das Auth-Modell und das Patch-Ziel bei der Installation.

Wenn webblocks:install nach einem fehlgeschlagenen oder unterbrochenen vorherigen Lauf stoppt, führen Sie es zunächst ohne Reparatur erneut aus und lesen Sie die Diagnose zur partiellen Installation. Leere CMS-Tabellen können explizit beiseitegeschoben werden:

Der Reparaturmodus benennt nur leere CMS-eigene Kandidatentabellen um. Er löscht keine Tabellen, ändert nicht-leere Tabellen nicht automatisch und geht nicht davon aus, dass das CMS die Host-Anwendung besitzt.

Verwenden Sie den Browser-Assistenten für eine Neuinstallation.

Sobald der Quellcode lokal vorhanden ist, starten Sie mit:

Öffnen Sie dann http://127.0.0.1:8000/install.

Der Assistent deckt ab:

• Prüfungen der Umgebungsbereitschaft
• Datenbankkonfiguration und Verbindungsvalidierung
• Kern-CMS-Installation
• Erstellung des ersten super_admin
• Sperrung der Installation nach Abschluss

Hinweise:

• der Installer ist für Neuinstallationen gedacht
• wenn die Einrichtung unvollständig ist, kann der Assistent sicher erneut geöffnet und fortgesetzt werden
• nach Abschluss werden die Installationsrouten gesperrt und der normale Auth-/Admin-Ablauf übernimmt
• der Installer schreibt die gewählte Datenbankkonfiguration in .env

Verwenden Sie den CLI-Ablauf, wenn Sie für eine Neuinstallation einen standardmäßigen Laravel-Einrichtungsweg bevorzugen.

Hinweise:

• php artisan db:seed installiert die Kern-CMS-Kataloge und speichert die aktuelle App-Version als installierte Version für eine Neuinstallation
• php artisan storage:link ist erforderlich, wenn die öffentliche Dateiauslieferung storage/app/public verwenden soll
• Laufzeitverzeichnisse unter storage/framework, storage/logs und bootstrap/cache werden beim ersten Start automatisch erstellt
• Backup / Restore speichert Archive auf der backups-Dateisystem-Disk, standardmäßig unter storage/app/backups. Der PHP-Laufzeitbenutzer sollte Eigentümer dieses Verzeichnisses sein oder eine Deployment-Gruppe mit Lese-/Schreibzugriff teilen; vermeiden Sie pauschale 777-Modi.

Für ein frisches Laravel-Projekt, das mit lokal installiertem PHP und Composer läuft:

Öffnen Sie dann:

• öffentliche Site: /
• Admin-Anmeldung: /webadmin/login
• Admin: /webadmin

Sobald der Quellcode lokal vorhanden ist:

Hinweise:

• vertrauenswürdige lokale Entwicklung sollte .test-Domains und HTTPS verwenden, mit https://webblocks-cms.test als kanonischer CMS-Entwicklungs-URL
• php artisan serve bleibt für schnelle, rein CLI-basierte Prüfungen nützlich, aber vertrauenswürdige Browser-Workflows sollten das in docs/native-local-development.md dokumentierte native Nginx/PHP-FPM-Setup verwenden
• lokale Kontaktformular-E-Mail-Benachrichtigungen sollten einen lokalen SMTP-Catcher oder ein vertrauenswürdiges SMTP-Testkonto verwenden; die üblichen lokalen SMTP-Werte hängen vom installierten Tool ab
• Empfänger von Kontaktformular-Benachrichtigungen werden in dieser Reihenfolge aufgelöst: recipient_email auf Blockebene, Standard-Kontaktempfänger der aktuellen Site, CONTACT_RECIPIENT_EMAIL, dann MAIL_FROM_ADDRESS als letzter sicherer Fallback
• Kontaktübermittlungen werden unabhängig von der Benachrichtigungszustellung gespeichert; eine öffentliche Message sent-Antwort bestätigt also den Speichererfolg, selbst wenn der Admin-Bereich die Benachrichtigung später als Failed, Skipped oder Not configured anzeigt
• MAIL_MAILER=log, MAIL_MAILER=array und MAIL_MAILER=null sind keine echte ausgehende Zustellung und werden für die Kontaktnachrichten-Benachrichtigung als nicht konfiguriert angezeigt
• Kontaktformular-Blöcke rendern einen CMS-eigenen versteckten .wb-form-check-Wrapper mit inert, aria-hidden="true", einem vom Renderer generierten form_check_{token}-Feld, tabindex="-1" und autocomplete="off"; wenn dieses generierte Prüffeld ausgefüllt wird, gibt der Server dieselbe generische Erfolgsweiterleitung zurück und speichert keine Kontaktnachricht und versucht keine Benachrichtigung
• Übermittlungen, die das generierte Prüffeld passieren, können dennoch durch konservative gespeicherte Signale wie kommerzielle Ansprache-Sprache, Linkdichte, wiederholte Übermittlungen von derselben IP oder ein Freemail-Verkaufsanschreiben mit generischem Betreff als spam eingestuft werden; dieser Status ist eine dauerhafte Admin-Klassifizierung und ist vom E-Mail-Benachrichtigungsstatus getrennt
• wenn die Benachrichtigungszustellung fehlschlägt, können Admins die gespeicherte Nachricht unter Admin -> Contact Messages einsehen, um den kompakten Fehlerstatus in der Liste und die gespeicherten Fehlerdetails auf dem Nachrichtendetailbildschirm zu sehen

Öffnen Sie dann:

• öffentliche Site: https://webblocks-cms.test
• Admin: https://webblocks-cms.test/webadmin
• Installer bei einer Neuinstallation: https://webblocks-cms.test/install

Schließen Sie die Neuinstallation im Browser-Assistenten ab, nachdem diese Einrichtungsschritte erledigt sind.

• Neuinstallationen leiten automatisch zu /install weiter
• Sie können den Assistenten auch manuell unter /install öffnen
• Sie können /install/core öffnen, um direkt zum Kern-Installationsschritt zu springen, wenn frühere Anforderungen bereits erfüllt sind
• der Assistent kann Schritte automatisch weiterschalten, sobald Anforderungen erfüllt sind
• das Öffnen von / und /install in mehreren Browser-Tabs kann unterschiedliche Assistentenschritte anzeigen; das ist zu erwarten, weil der Installer den Fortschritt verfolgt und entsprechend weiterleitet

Der erste super_admin ist für eine abgeschlossene Installation erforderlich.

• erstellen Sie im Browser-Assistenten den ersten Admin im letzten Einrichtungsschritt
• geben Sie im Paket-Consumer-CLI-Ablauf --name, --email und --password an webblocks:install weiter
• stellen Sie bei einer manuellen Installation sicher, dass mindestens ein aktives super_admin-Konto existiert, bevor das CMS als vollständig installiert gilt

super_admin ist die Rolle auf Installationsebene, die auf Benutzer, Sites, Sprachen (Locales), Einstellungen, Updates, Backups, Export/Import und alle Site-Inhalte zugreifen kann.

• der Installer wird nach Abschluss gesperrt
• /webadmin ist der kanonische Einstiegspunkt in den CMS-Admin-Bereich
• Paket-Consumer-Installationen können sich über /webadmin/login anmelden; co-installierte Apps können ihr host-eigenes /login behalten
• /webadmin/dashboard leitet zu /webadmin weiter
• CMS-Assets bleiben unter /cms, zum Beispiel /cms/css, /cms/js und /cms/brand
• das paketeigene /webadmin/login verwendet Paket-Blade-Views, die Gast-Auth-Shell der WebBlocks UI, gepinnte WebBlocks-UI-Assets, /cms/css/guest.css und CMS-Produkt-Markenassets aus /cms/brand, einschließlich der Favicon-/Browser-Tab-Varianten normal, dunkle Oberfläche, auf Akzentfarbe/invers und hoher Kontrast
• /cms ist für CMS-eigene statische öffentliche Assets reserviert und darf nicht als Präfix, Alias oder Weiterleitung für CMS-Admin-Routen verwendet werden
• /admin gehört nicht dem CMS und darf nicht als CMS-Admin-Route wiederhergestellt werden
• neue Seiten beginnen als draft
• wenn Funktionen auf Installationsebene wie Revisionen, Backups oder Updates fehlende Tabellen melden, führen Sie php artisan migrate aus

Die Trennung von /webadmin und /cms vermeidet die Nginx-try_files-Kollision, bei der /cms/ als physisches public/cms/-Asset-Verzeichnis aufgelöst werden kann, bevor Laravel eine Route verarbeitet. Lösen Sie den Admin-Zugriff nicht durch Hinzufügen einer public/cms/index.php-Übergabe; diese Front-Controller-Brücke muss in den öffentlichen Assets von Root und Paket abwesend bleiben.

Konfigurieren Sie den Laravel-Mailversand, bevor Sie eine öffentliche Kontaktseite veröffentlichen. Ein typisches SMTP-.env-Setup sieht so aus:

MAIL_* steuert den Laravel-Mailversand für Benachrichtigungsversuche des Kontaktformulars. MAIL_FROM_ADDRESS ist die sichere Fallback-Absenderadresse und zugleich der letzte sichere Empfänger-Fallback des Kontaktformulars, wenn kein spezifischerer Empfänger konfiguriert ist. CONTACT_RECIPIENT_EMAIL ist optional und dient als Fallback-Empfänger auf Umgebungsebene. Bevorzugen Sie, wenn verfügbar, die Konfiguration des Kontakt-Empfängers auf Site-Ebene unter Site -> Edit -> Contact, damit das Kontakt-Routing bei der Site liegt und nicht nur in .env.

Leeren Sie nach dem Ändern der .env-Maileinstellungen in Produktions- oder Paketinstallationen die zwischengespeicherte Konfiguration, wenn die Installation Config-Caching verwendet:

Kontaktformular-Benachrichtigungen lösen Empfänger in dieser Reihenfolge auf:

1. Kontaktformular-Block recipient_email
2. Standard-Kontaktempfänger der Site aus Site -> Edit -> Contact
3. .env CONTACT_RECIPIENT_EMAIL
4. sicherer MAIL_FROM_ADDRESS-Fallback

Angenommene echte Kontaktformular-Übermittlungen werden gespeichert, bevor eine E-Mail-Benachrichtigung versucht wird. Ein Benachrichtigungsfehler bedeutet nicht, dass die öffentliche Formularübermittlung fehlgeschlagen ist. Admins sollten /webadmin/contact-messages auf gespeicherte Nachrichten, den Benachrichtigungsstatus und sichere Fehlerdetails prüfen. Öffentliche Besucher sollten nur normales Erfolgs- oder Validierungsfeedback sehen, keine Mail-Diagnosen.

Sent bedeutet, dass das CMS die Benachrichtigung ohne Exception an den konfigurierten Mail-Transport übergeben hat; es garantiert keine Zustellung in den Posteingang. Skipped oder Not configured bedeutet, dass kein echter Benachrichtigungsversand versucht wurde.

Verwenden Sie für Kontaktseiten den nativen contact_form-Block. Ersetzen Sie ihn nicht durch Trusted HTML, rohes <form>-Markup oder mailto:-Fallbacks. Der CMS-Renderer generiert das versteckte Anti-Spam-Prüffeld automatisch; legen Sie es nicht manuell an. Das alte website-Honeypot-Feld ist nicht mehr Teil des öffentlichen Vertrags.

Praktischer Kontaktformular-Smoke-Test:

1. Veröffentlichen Sie eine Seite mit dem nativen contact_form-Block oder zeigen Sie sie in der Vorschau an.
2. Senden Sie eine Testnachricht mit Name, E-Mail, Betreff und Nachricht.
3. Öffnen Sie /webadmin/contact-messages.
4. Bestätigen Sie, dass die Nachricht gespeichert wurde.
5. Prüfen Sie den Benachrichtigungsstatus.
6. Wenn die E-Mail nicht angekommen ist, sehen Sie sich die sicheren Fehlerdetails an und führen Sie die Mail-Diagnose aus.

Diagnosebefehle:

Der Diagnosebefehl darf keine Passwörter, Tokens oder Mail-Geheimnisse ausgeben. Verwenden Sie --block=ID, um die Empfänger-Fallback-Kette für einen einzelnen Kontaktformular-Block zu untersuchen. Verwenden Sie --send-test= nur für eine kontrollierte SMTP-Sendeprüfung an eine bewusst gewählte Testadresse.

1. Melden Sie sich unter /webadmin an.
2. Überprüfen Sie Ihre Site- und Sprachkonfiguration (Locale).
3. Konfigurieren Sie die Site-Identität und die Domains.
4. Konfigurieren Sie die Laravel-Maileinstellungen oder freigegebene System-Maileinstellungen.
5. Konfigurieren Sie einen Kontaktformular-Empfänger, vorzugsweise unter Site -> Edit -> Contact.
6. Führen Sie php artisan contact:mail-diagnose aus.
7. Senden Sie ein natives Test-Kontaktformular und bestätigen Sie, dass es eine Kontaktnachricht speichert.
8. Überprüfen Sie den E-Mail-Benachrichtigungsstatus für diese Testnachricht.
9. Erstellen Sie Ihre erste Seite.
10. Fügen Sie Medien, Navigation und Blöcke hinzu.
11. Veröffentlichen Sie Inhalte über den redaktionellen Workflow.