04 — Installation in ein bestehendes TYPO3

Das ZIP aus dem Kundenportal ist ein ganzes Projekt, und 03 — DDEV richtet dieses Projekt von Grund auf ein. Wenn bereits eine TYPO3-v14-Installation steht — eigenes Hosting, eigenes Deployment, eigene Site-Konfiguration —, nimmt man die beiden Extension-Ordner aus dem ZIP und lässt den Rest liegen.

Das funktioniert mit und ohne Demo-Inhalte und sowohl im Composer als auch im Classic Mode. Ob die Installation unter DDEV läuft, spielt hier keine Rolle: Die Umgebung steht bereits, und es ändert sich nur das Präfix der Befehle (ddev typo3 … statt vendor/bin/typo3 …).

0. Datenbank und Projekt sichern

Das gehört vor das Entpacken. Hier kommt eine Extension in eine Site, in der bereits die Inhalte anderer Leute stehen, und zwei der folgenden Schritte schreiben an Stellen, für die es kein Rückgängig gibt: extension:setup führt Datenbankmigrationen aus und kopiert Dateien nach fileadmin/.

mysqldump -u <user> -p <database> | gzip > backup-$(date +%F).sql.gz
tar czf project-$(date +%F).tar.gz /path/to/project

Unter DDEV:

ddev snapshot
ddev export-db --file=backup-$(date +%F).sql.gz

Beides aufbewahren — der Dump allein reicht nicht. Eine Datenbank, die neben den neuen Extension-Dateien zurückgespielt wird, ist ein anderer Zustand als der Ausgangszustand, und das kompilierte CSS des Themes, config/sites/<id>/settings.yaml und fileadmin/ liegen allesamt außerhalb der Datenbank.

1. Die Extensions aus dem ZIP holen

unzip yavi-lucerne.zip -d /tmp/yavi

Zwei Ordner daraus werden gebraucht:

/tmp/yavi/yavi-lucerne/packages/yavi-core/
/tmp/yavi/yavi-lucerne/packages/yavi-lucerne/

Maßgeblich ist der Ordner, der unmittelbar ext_emconf.php enthält — das ist die Extension.

Wer auch die Demo-Inhalte will, behält das ZIP: Schritt 4a braucht .tarballs/yavi-lucerne-demo.t3d daraus.

2a. Composer Mode — ein path-Repository

So ist die Auslieferung gedacht. Beide Ordner unter packages/ ablegen:

packages/yavi-core/
packages/yavi-lucerne/

Dann das path-Repository in die composer.json des Projekts eintragen und die beiden Pakete anfordern:

{
  "repositories": [
    { "type": "path", "url": "./packages/*" }
  ],
  "require": {
    "webagentur-yahya/yavi-core": "dev-main",
    "webagentur-yahya/yavi-lucerne": "dev-main"
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}

Die Version lautet dev-main, nicht ^1.0 oder *. Die Pakete kommen aus einem ZIP und nicht aus einem getaggten Repository; das path-Repository hat also kein Tag, aus dem es eine Version lesen könnte, und bietet sie als Branch-Version dev-main an — eine dev-Stabilität. Unter Composers Vorgabe minimum-stability: stable ist diese Version unsichtbar, und "*" scheitert mit could not find a version matching your minimum-stability. Daher die beiden zusätzlichen Schlüssel: minimum-stability: dev macht die Branch-Version akzeptabel, und prefer-stable: true hält alles Übrige — TYPO3, Bootstrap Package, die eigenen Abhängigkeiten — auf stabilen Releases.

composer update "webagentur-yahya/*"
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

composer update, nicht composer install. Die composer.json wurde von Hand bearbeitet, die Lock-Datei kennt die beiden neuen Pakete also noch nicht; composer install installiert, was in der Lock-Datei steht, und täte entweder nichts oder verweigerte den Dienst. Das Update auf webagentur-yahya/* zu begrenzen hält jede andere Abhängigkeit auf der Version, die die Lock-Datei festschreibt.

extension:setup aktiviert die Extensions, führt die Datenbankmigrationen aus — gut ein Dutzend Spalten auf tt_content, dazu die Tabellen für Karussell-, Karten- und Portfolio-Einträge — und kopiert die initialen Dateien. Einen Befehl database:updateschema gibt es in TYPO3 v14 nicht; der stammt aus typo3_console und gehört nicht zum Core. extension:setup erledigt diese Arbeit.

Composer verlinkt packages/* symbolisch nach vendor/; eine Änderung an einem Template wirkt also sofort — kein Kopierschritt, kein Watcher.

Bootstrap Package 16 ist eine harte Abhängigkeit und liegt nicht im ZIP. Composer löst es wie gewohnt über Packagist auf; das Projekt braucht also Netzzugriff auf Packagist, obwohl die Yavi-Pakete nicht von dort kommen.

2b. Classic Mode

Für Installationen ohne Composer. Es funktioniert, aber die Abhängigkeitsverwaltung, die sonst Composer übernimmt, liegt dann bei dir.

typo3conf/ext/container/
typo3conf/ext/bootstrap_package/
typo3conf/ext/yavi-core/
typo3conf/ext/yavi-lucerne/

In dieser Reihenfolge unter Admin Tools → Extensions aktivieren, danach typo3/sysext/core/bin/typo3 extension:setup ausführen — im Classic Mode liegt die Binärdatei dort und nicht in vendor/bin/.

Der Classic Mode unterscheidet sich an mehr Stellen vom Composer-Weg als nur an dieser — am Document Root, am Ort der Site-Konfigurationen und daran, wie eine Extension überhaupt aktiviert wird. 04b — Installation im Classic Mode geht den gesamten Weg durch und führt jeden abweichenden Pfad in einer Tabelle auf.

Jeder Pfad weiter unten, der packages/yavi-lucerne/ nennt, lautet im Classic Mode typo3conf/ext/yavi-lucerne/.

3. Was die Aktivierung tut — und was nicht

Bei der ersten Aktivierung der Extensions:

Der Kopiervorgang läuft einmal je Extension und wird in sys_registry unter extensionDataImport vermerkt; beim nächsten extension:setup wiederholt er sich also nicht.

Diese Kopie ist nicht das, was die Demo-Inhalte verwenden. Die Dateidatensätze der Demo zeigen auf fileadmin/dummy-media/…, und der Import in Schritt 4a bringt eigene Kopien der Dateien mit, die er braucht. fileadmin/yavi_lucerne/ liegt bereit, damit das Material zur Hand ist; wer es auf einer Produktivsite nicht will, löscht den Ordner nach der Installation — der Registry-Eintrag hält ihn davon ab, wiederzukommen.

4. Über die Demo-Inhalte entscheiden

4a. Mit den Demo-Inhalten

Die Demo für eine bestehende Installation ist .tarballs/yavi-lucerne-demo.t3d aus dem ZIP — ein impexp-Inhaltspaket, 27 MB, mit allen Bildern, Videos und Audiodateien in der Datei selbst. Es ist nicht der Datenbank-Dump, und es ersetzt nichts: Es fügt auf Wurzelebene einen neuen Seitenbaum hinzu und lässt eigene Seiten, Inhalte und Benutzer unangetastet.

Die Datei ins Projekt kopieren und importieren:

mkdir -p .tarballs
cp /tmp/yavi/yavi-lucerne/.tarballs/yavi-lucerne-demo.t3d .tarballs/
vendor/bin/typo3 impexp:import /full/path/to/project/.tarballs/yavi-lucerne-demo.t3d 0

Unter DDEV ist es der Pfad innerhalb des Containers:

ddev typo3 impexp:import /var/www/html/.tarballs/yavi-lucerne-demo.t3d 0

Es dauert etwa zehn Sekunden und endet mit

 [OK] Importing … succeeded.

Danach steht neben der eigenen eine zweite Wurzelseite namens Home, mit 59 Seiten, 233 Inhaltselementen und 194 Mediendateien darunter. Weiter mit Schritt 5 — der neue Baum braucht eine eigene Site-Konfiguration, bevor er rendert.

Stattdessen über das Backend. Wer die Kommandozeile meiden will, führt dieselbe Datei über Import/Export ein: Sie gehört nach fileadmin/user_upload/_temp_/importexport/; danach mit der rechten Maustaste auf die Wurzel des Seitenbaums klicken, More options → Import wählen, die Datei auswählen und den Import starten. Eine 27-MB-Datei über das Formular hochzuladen setzt voraus, dass upload_max_filesize und post_max_size das erlauben; die Datei per SFTP in diesen Ordner zu legen umgeht die Frage.

Was das Demo-Paket nicht enthält. Die zweite Sprache der Demo steckt nicht in dieser Datei — nur die Standardsprache. TYPO3 synchronisiert Übersetzungen, während es die importierten Relationen auflöst, und bei einem Import dieser Größe endet das in einem Fehler, der den gesamten Import ohne Angabe einer Ursache abbricht. Der Verlust ist gering: Die zweite Sprache der Demo deckt 1 von 60 Seiten ab, und ihr Text ist ohnehin englisch. Eine frische Installation aus dem Datenbank-Dump (03, 03b) hat jede Übersetzung — ein Dump ist ein Dump.

4b. Ohne die Demo-Inhalte

Nichts zu tun. Die Extensions bringen keinen Inhaltsimport mit; der Seitenbaum ist also bereits genau so, wie er war. Weiter mit Schritt 5.

Das Aussehen des Themes stammt nicht aus der Demo-Datenbank. Es stammt aus dem Set und den Einstellungen in config/sites/<id>/settings.yaml, und darum geht es in 05 — Die erste Site einrichten. Eine leere Site mit aktiviertem Set und gültiger Lizenz rendert vom ersten angelegten Seite an im Design des Themes.

5. Die Site-Konfiguration

TYPO3 importiert das Initialisation/Site/ eines Pakets nur zusammen mit einem Inhaltsimport aus Initialisation/data.t3d/data.xml — ohne einen solchen kehrt der Importer vorzeitig zurück. Da die Extensions keine Importdatei mitbringen, wird Initialisation/Site/ nie automatisch angewendet.

Ein Site-Ordner enthält drei Dateien, und das Theme braucht alle drei:

page.tsconfig und settings.yaml liest TYPO3 selbstständig ein, sobald sie im Site-Ordner liegen — es ist nirgends etwas einzubinden.

Ohne Demo (4b) bleibt die vorhandene Site-Konfiguration bestehen und wird um die fehlenden Teile ergänzt. Zuerst die Sets: in config/sites/<id>/config.yaml den Schlüssel dependencies erweitern — die Reihenfolge zählt, jedes baut auf dem darüber auf:

dependencies:
  - bootstrap-package/full
  - yavi-core/full
  - yavi-lucerne/full

Dieselbe Liste lässt sich im Backend unter Site Management → Sites bearbeiten. Alles Übrige — Base, Sprachen, Fehlerbehandlung — bleibt, wie es ist. Die mitgelieferte config.yaml nicht über eine konfigurierte Site kopieren; das setzte alles davon zurück.

Dann die beiden anderen Dateien, die die Site noch nicht hat:

cp packages/yavi-lucerne/Initialisation/Site/yavilucerne/page.tsconfig \
   packages/yavi-lucerne/Initialisation/Site/yavilucerne/settings.yaml \
   config/sites/<id>/

Danach den Cache leeren; die Sets bringen TypoScript mit.

Anschließend der Wurzelseite ein Backend-Layout geben: Seiteneigenschaften → Erscheinungsbild → Backend-Layout (nur diese Seite) und (Unterseiten dieser Seite), beide auf Yavi Core – Standard. Bestehende Seiten tragen das Layout, das sie vorher hatten, und das ist keines des Themes — ohne diesen Schritt haben sie keine Spalten, die das Theme adressiert, und das Frontend rendert einen leeren Rahmen. Siehe 05 — Die erste Site einrichten.

Mit Demo (4a) ist der importierte Baum eine neue Wurzelseite und braucht eine eigene Site-Konfiguration. Die mitgelieferte ist ein brauchbarer Ausgangspunkt:

mkdir -p config/sites/demo
cp -R packages/yavi-lucerne/Initialisation/Site/yavilucerne/. config/sites/demo/

Danach config/sites/demo/config.yaml bearbeiten:

Die base muss absolut sein. Mit einem relativen /demo/ neben einer bestehenden Site, deren Base den Host trägt, ordnet TYPO3 die Anfrage der neuen Site nicht zu und beantwortet jede URL darunter mit einem 404.

Den Block baseVariants entfernen, sofern nicht DDEV im Spiel ist — er trägt %env(DDEV_BASE)%-Platzhalter, die sich anderswo zu nichts auflösen.

Der Lizenzschlüssel in der mitgelieferten settings.yaml ist bewusst leer, damit nie ein Schlüssel verteilt wird. Den eigenen eintragen wie in 05 — Die erste Site einrichten beschrieben.

6. Dateirechte prüfen

Der Webserver-Benutzer muss schreiben können:

• config/sites/<id>/settings.yaml — sonst kann das Backend-Modul nicht speichern
• typo3temp/assets/ — sonst lässt sich das kompilierte CSS nicht schreiben
• var/cache/
• fileadmin/ — für Uploads und für die selbst gehosteten Google-Schriften

7. Weiter

Das Set aktivieren und die Lizenz eintragen — 05 — Die erste Site einrichten.

Updates

Neue Versionen kommen von **licence.yavithemes.com → Konto → Downloads**. Dort das Framework update verwenden — yavi-core-<version>.zip, rund 5 MB. Das vollständige Paket ist für eine Erstinstallation. Die Seite zeigt je Lizenz ein Datum Updates until; die Site läuft weiter, wenn es verstreicht — ein abgelaufenes Fenster blockiert neue Versionen, nicht das Installierte.

Aktualisiert wird nur yavi-core. Die Theme-Extension gehört dir — ihr SCSS, ihre Templates, ihre Einstellungen —, und ein Update darf diese Arbeit nicht überschreiben.

1. Datenbank und Projekt sichern, genau wie in Schritt 0. Ein Update führt die Datenbankmigrationen erneut aus, und eine Schemaänderung lässt sich nicht dadurch rückgängig machen, dass man die alten Dateien zurücklegt.
2. Die Site in den Wartungsmodus setzen — oder ein paar Sekunden kaputtes Layout in Kauf nehmen.
3. Den alten yavi-core-Ordner löschen — nicht darüber entpacken. Dateien, die die neue Version entfernt hat, blieben sonst liegen, und ein übrig gebliebenes SCSS-Partial, das irgendwo noch per @import eingebunden ist, ist ein schwer zu findender Fehler.
4. Die neue Version an dieselbe Stelle entpacken. Den Theme-Ordner in Ruhe lassen.
5. Im Composer Mode composer dump-autoload ausführen, damit der Autoloader neue PHP-Klassen aufnimmt.
6. vendor/bin/typo3 extension:setup && vendor/bin/typo3 cache:flush

Der Cache-Flush ist nicht optional. Das kompilierte theme-<hash>.css ist über den SCSS-Inhalt geschlüsselt; ohne Flush wird weiterhin die alte Datei ausgeliefert.

Ein Update rührt nie Inhalte an. Weder der Demo-Import noch die eigenen Seiten sind davon betroffen.

Bekannte Grenzen des Classic Mode