Installation & Updates
Dieses Kapitel ist der verbindliche Betriebsvertrag für Neuinstallationen, Release-Updates und Datenbankänderungen. Maßgeblich ist immer die lokale Installation. Das Release-Verzeichnis ist eine daraus erzeugte, geprüfte Veröffentlichung und keine zweite Entwicklungsquelle.
Grundsatz: Die DD entscheidet, nicht die Datenbankart
Jede DD besitzt in $table['server'] einen ausgelieferten Standardserver. Eine Installation darf diesen Standard für jede einzelne DD lokal überschreiben. Dadurch sind in derselben Installation gleichzeitig möglich:
- DDs in verschiedenen .db3-Dateien;
- mehrere DDs in derselben .db3-Datei;
- einzelne DDs auf MySQL/MariaDB;
- weitere DDs weiterhin auf SQLite;
- DDs verschiedener Module auf unterschiedlichen SQL-Servern.
Fachmodule merken davon nichts. Sie verwenden weiterhin ausschließlich eine DD-Referenz und dbxDB:
Direkter PDO-, SQLite- oder MySQL-Code im Modul, Installer oder in einer Migration ist nicht zulässig.
Auflösung einer Serverbindung
Die lokale Konfiguration liegt ausschließlich in:
config.php enthält nur den ausgelieferten Standard:
Eine lokale gemischte Installation kann beispielsweise so gebunden sein:
dbxApp ist dabei der Name eines aktiven Eintrags in $config['db']. Ein Wert wie dbxShop|dbxShop.db3 ist ein DD-/DB3-Serverziel.
Die Auflösung ist eindeutig:
- exakte lokale Bindung modul|dd;
- kompatible ältere Bindung nur über den nackten DD-Namen;
- andernfalls $table['server'] aus der DD.
Eine vorhandene, aber ungültige lokale Bindung fällt bewusst nicht auf den DD-Standard zurück. Sie wird als Konfigurationsfehler abgelehnt. So kann ein Tippfehler niemals unbemerkt auf die falsche Datenbank schreiben.
Der aktuelle Zustand kann ohne Datenmutation geprüft werden:
Die Rückgabe nennt deklarierten und aufgelösten Server, Quelle und Gültigkeit.
Administration
Unter System → DD-Serverbindungen listet dbxAdmin alle gefundenen DDs. Jede DD kann unabhängig auf:
- ihren ausgelieferten DD-Standard;
- einen aktiven konfigurierten SQL-Server;
- ihr bisheriges explizites DB3-Ziel
gesetzt werden. Gespeichert werden nur Abweichungen. Passwörter und andere lokale Datenbankwerte werden dabei nicht neu geschrieben.
Eine Zieländerung verschiebt keine Daten. Erst ein ausdrücklicher Transfer-/Migrationsprozess darf Tabellen und Datensätze auf ein anderes Ziel übertragen.
Neuinstallation und Installationsschalter
Eine vollständige Installationsausgabe kann über dbxapp.de bereitgestellt werden. Produktive .db3-Dateien aus der Entwicklungsinstallation gehören nicht in ein öffentliches Quell- oder Updatepaket.
Eine Auslieferung startet mit:
Solange dieser Wert aktiv ist, wird jeder dynamische Seitenaufruf vor Permalink-, Content-, Session-DB- und Seiten-Cache-Zugriffen verbindlich auf dbxSetup und das eigenständige Installationsdesign geleitet. Nach erfolgreichem Abschluss speichert der Assistent ausschließlich in der lokalen, updategeschützten config.local.php:
Der Installer arbeitet in sieben nachvollziehbaren Schritten:
- PHP-Version, notwendige Erweiterungen, Composer-Abhängigkeiten und Schreibrechte prüfen. Optionale Erweiterungen werden getrennt ausgewiesen.
- Seitentitel, Markenname, Claim, Standardsprache, Zeitzone sowie Benutzer- und Admin-Design festlegen.
- Zielmodell wählen: die vollständig ausgelieferten DB3-Dateien direkt verwenden, alle DDs auf einen geprüften PDO-Server oder vorhandene Einzelbindungen setzen. Unterstützte Installationsziele sind zunächst MySQL/MariaDB, PostgreSQL und Microsoft SQL Server. Vorhandene nicht geheime Serverwerte werden als Formularvorgaben übernommen; leere Passwortfelder bewahren ein bereits lokal gespeichertes Passwort.
- Im DB3-Standard alle vorhandenen Tabellen ausschließlich lesend auf Vollständigkeit prüfen. Nur für ein gewähltes PDO-Ziel werden die DD-Schemas synchronisiert. Eine optionale, ausdrücklich bestätigte Übertragung kann vorhandene lokale DD-Tabellen erst danach auf das erreichbare SQL-Ziel kopieren.
- Den Administrator admin mit einem persönlichen Passwort einrichten. Passwort und Wiederholung werden bereits im Assistenten geprüft; Groß- und Kleinbuchstaben, eine Zahl und ein Sonderzeichen sind verbindlich, zwölf oder mehr Zeichen werden empfohlen. Fehlt der Benutzer, wird er angelegt. Ist er bereits vorhanden, aktualisiert der Installer das ausdrücklich eingegebene Passwort, aktiviert und bestätigt das Konto und stellt die Admin-Rolle sicher. Andere Profildaten und nicht installationsbezogene Einstellungen bleiben erhalten.
- Globalen E-Mail-Betrieb, Transport, SMTP-Zugang, sichtbaren Absender, Envelope-Absender und erlaubte Absenderdomains konfigurieren.
- Eine geheimnisfreie Zusammenfassung bestätigen und die Installation lokal aktivieren.
Der Installer verändert keine vorhandenen Gruppen. Das persönliche Admin-Passwort wird ausschließlich mit password_hash() gespeichert und nie in Zusammenfassungen, Protokollen oder der lokalen Konfiguration ausgegeben. Eine bestätigte erneute Installation darf das Konto nur mit dem erneut eingegebenen persönlichen Passwort aktualisieren. Wiederholtes Ausführen erzeugt keine doppelten Seed-Datensätze.
PDO-Migration
Eine Migration wird nur angeboten, nachdem Servertyp, Host, Datenbank, Benutzer und Port erfasst wurden. Vor dem Speichern der DD-Bindungen muss eine Verbindung direkt zur Zieldatenbank gelingen. Existiert die Datenbank noch nicht, darf der Assistent sie nur nach ausdrücklicher Auswahl und mit einem dafür berechtigten Konto anlegen; anschließend wird die Verbindung zur angelegten Datenbank erneut geprüft.
Erst im folgenden, getrennt bestätigten Schritt werden Zieltabellen aus den DDs erzeugt und – falls ebenfalls ausdrücklich gewählt – vorhandene DB3-Daten übertragen. Ein Verbindungs-, Anlege- oder Prüfungsfehler beendet den Ablauf vor jeder Schema- oder Datenmigration.
Hilfe im Installationsassistenten
Schritt 3 bietet zwei direkt erreichbare openWin-Hilfen:
- Mitgelieferte DB3 genau erklärt beschreibt den unveränderten Lieferzustand von Tabellenstruktur und Fachdaten sowie die ausschließlich lesende Vollständigkeitsprüfung. Das persönliche Admin-Passwort wird davon getrennt erst in Schritt 5 eingerichtet.
- PDO-Migration Schritt für Schritt trennt Serverdaten, Verbindung, optionale Datenbankanlage, erneute Verbindungsprüfung, DD-Strukturaufbau und die ausdrücklich zu bestätigende Datenübertragung.
Beide Hilfen werden ohne Formularübermittlung geöffnet. Sie zeigen keine Zugangsdaten und weisen klar darauf hin, dass ohne erfolgreiche Zielverbindung keine Schema- oder Datenänderung startet.
Globaler E-Mail-Betrieb
$config['mail_delivery_mode'] gilt vor allen Modulkonfigurationen:
| Wert | Verhalten |
|---|---|
| internal | Kein Netzwerkversand. Empfänger, Absender und Betreff werden als internes Mailereignis in dbxSysMsg angenommen; Inhalt und Anhänge werden nicht gespeichert. |
| external | Der ausgewählte PHP-Mail-, Sendmail- oder SMTP-Transport darf Nachrichten versenden. |
| disabled | Das Mailereignis wird abgelehnt und die globale Sperre intern protokolliert. |
Der sichere Auslieferungsstandard ist internal. SMTP-Zugang und Absender können bereits vollständig vorbereitet werden, während externer Versand noch ausgeschaltet bleibt.
Der globale Profilabsender ist nur der Rückfallwert für allgemeine Systemnachrichten. Geschäftsprozesse besitzen getrennte, lokal gespeicherte From-Adressen:
| Prozess | Konfigurationswert | Vorgabe |
|---|---|---|
| Kontaktanfragen, Eingangsbestätigungen und Supportantworten | dbxContact.mail_from | kontakt@dbxapp.de |
| Bestellungen, Bestellstatus und Widerrufe | dbxShop.mail_from | shop@dbxapp.de |
Beide Werte sind in Installationsschritt 6 frei eingebbar und werden zusammen mit mail_profile = dbxApp in der jeweiligen config.local.php gespeichert. Das Kontaktformular verwendet die Adresse des Anfragenden ausschließlich als Reply-To; dadurch bleibt der sichtbare Absender stabil und clientseitige Mailregeln können Kontakt- und Shop-Prozesse zuverlässig unterscheiden. Ist force_from im globalen Mailprofil aktiviert, ersetzt der Maildienst bewusst beide Modulabsender durch den globalen From-Wert.
Datenbankmigration eines Moduls
Eine Release-Migration liegt unter:
Minimales Beispiel:
Verbindliche Regeln:
- Die ID ist dauerhaft eindeutig und wird nach Veröffentlichung nie geändert.
- Die Versionsnummer ist die erste Release-Version, welche die Änderung benötigt.
- Jede möglicherweise veränderte DD steht in affected_dd.
- Schemaänderungen stammen aus der neuen DD und laufen als sync_dd.
- Fachliche Datenänderungen verwenden ausschließlich das an up übergebene dbxDB-/dbxDD-Objekt.
- Eine Migration wird niemals durch direkte SQL-Dateien oder PDO ergänzt.
- Bereits ausgeführte Migrationen dürfen nicht nachträglich verändert werden; der SHA-256-Abgleich würde das Update absichtlich stoppen.
sync_dd verwendet standardmäßig den sicheren Modus apply: fehlende Felder und Indizes werden ergänzt, ein notwendiger Tabellen-Rebuild stoppt dagegen mit einer Fehlermeldung. Nur wenn der Release-Autor den bereits gesicherten Rebuild bewusst geprüft hat, wird er explizit angefordert:
Ein optionales up erhält die systemweiten Fassaden:
Für wiederkehrende Seeds ist ein idempotenter Installationsservice zu verwenden. Migrationen dürfen keine lokalen Servernamen voraussetzen.
Update-Ablauf
Bis zum Start der Installation kann der Benutzer das vorbereitete Update vollständig stoppen. Der danach gestartete kritische DB-/Dateischritt ist bewusst nicht teilunterbrechbar. Ein Fehler löst automatisch den gemeinsamen Rollback von Datenbanktabellen und Dateien aus.
Vor einer Migration wird jede betroffene DD erneut aufgelöst. Die Sicherung wird nach dem tatsächlich verwendeten Server gruppiert. Damit bleibt ein Update korrekt, wenn beispielsweise Benutzer und Bestellungen auf MySQL, Content und Sessions aber in verschiedenen DB3-Dateien liegen.
Schutz gegen unbeabsichtigte Serverwechsel
Ändert ein Release den in einer DD ausgelieferten $table['server'], darf das Update eine bestehende Installation nicht stillschweigend auf das neue Ziel umlenken. Ohne explizite lokale Bindung wird der Updatevorgang abgelehnt.
Der Betreiber entscheidet dann bewusst:
- bisheriges Ziel als lokale DD-Bindung festschreiben; oder
- Daten mit dem vorgesehenen Transferprozess auf das neue Ziel übertragen und erst danach die Bindung ändern.
Das gilt auch für DB3-zu-MySQL- und MySQL-zu-DB3-Wechsel.
Migrations-Ledger und Rollback
Ausgeführte Migrationen werden in dbxAdmin|dbxMigration mit ID, Version, Modul, Checksum, Status, betroffenen Servern und Sicherungsreferenz protokolliert.
Vor dem ersten Schreibschritt werden Schema, Indizes und Daten jeder betroffenen existierenden Tabelle gesichert. Beim Rollback werden:
- neu angelegte Tabellen entfernt;
- frühere Tabellenstrukturen und Indizes wiederhergestellt;
- gesicherte Daten zurückgespielt;
- der Migrationsstatus als zurückgerollt markiert;
- geänderte Programmdateien aus derselben Updatesicherung wiederhergestellt.
Release-Verantwortung
Die Entwicklung findet im <dbxapp-quellverzeichnis> statt. Erst ein bewusster Release-Schritt synchronisiert den geprüften Quellstand nach <dbxapp-release-verzeichnis>, erstellt Inventar, ZIP, Prüfsummen und Manifest und veröffentlicht anschließend GitHub.
Installationsdaten und lokale Konfiguration werden nie von GitHub in eine bestehende Installation kopiert. Updates liefern Code, DDs und versionierte Migrationen. Die lokale DD-Serverbindung bleibt die Wahrheit der jeweiligen Installation.
Abnahmematrix
Vor Veröffentlichung eines Releases müssen mindestens bestanden sein:
- DD-Auflösung ohne Binding, mit DB3-Binding und mit SQL-Alias;
- parallele Auflösung zweier DDs auf unterschiedliche Serverarten;
- ungültige Bindung wird abgelehnt;
- install=1 erreicht den Assistenten ohne vorherigen DD-, Permalink- oder Seiten-Cache-Zugriff;
- notwendige Systemprüfungen blockieren den nächsten Schritt, optionale Prüfungen bleiben klar als Empfehlungen erkennbar;
- Neuinstallation, erneuter Seitenaufruf und wiederholte Seeds erzeugen keine doppelten Datensätze; der Benutzer admin erhält bei Bestätigung von Schritt 5 reproduzierbar das dort geprüfte persönliche Passwort, die Admin-Rolle und den Status aktiv und bestätigt; leere Passwortfelder für bestehende Server- und Mailzugänge bleiben unangetastet;
- unveränderte, rein lesend geprüfte DB3-Tabellenstruktur und Fachdaten sowie PDO-Installation: ohne erreichbare und vorhandene beziehungsweise erfolgreich angelegte Zieldatenbank darf weder Schema- noch Datenmigration starten;
- die globalen Mailmodi internal, disabled und external; insbesondere darf internal keinen Netzwerktransport starten und keinen Nachrichten- inhalt protokollieren;
- deutsche Installationsoberfläche auf Desktop und Mobilgerät ohne horizontalen Seitenüberlauf; Englisch und Spanisch folgen erst nach fachlicher und gestalterischer Freigabe der deutschen Fassung;
- Anmeldung mit dem in Schritt 5 gesetzten Admin-Passwort gelingt; falsche, schwache oder nicht übereinstimmende Passwörter werden bereits im Assistenten abgelehnt;
- Migrationserkennung, Checksum-Ledger und bereits ausgeführte Migration;
- Backup und Rollback über mindestens zwei verschieden gebundene Server;
- gemeinsamer Datei-/DB-Rollback bei simuliertem Fehler;
- bestehende dbxDB-, dbxForm-, dbxReport- und Update-Regressionstests;
- ein vollständiger Lauf des Moduls dbxSelfTest einschließlich der in der jeweiligen Installation verfügbaren PHP- und JavaScript-Tests.