Dieser Text enthält eine detaillierte Schritt-für-Schritt-Anleitung - inkl. aller Fehler und Fallen, die auftreten und in die man reintappen kann!

Ziel: Anderen zu helfen, solche Fehler zu vermeiden - denn keiner googelt nach nicht-Fehlern!

Mit Docker & DDEV sind die Zeiten des Gehampels mit Subdomains, Wamp, Xampp und FTP entgültig vorbei,

um Serverinstallationen als (Sicherungs-)Kopie einem Upgrade zu unterziehen.
Auf einem LIVE-System macht das ja nun wirklich niemand.

Es gibt inzwischen zwar - statt FTP - auch die angenehme Möglichkeit, mit einer IDE wie Visual Studio Code zu arbeiten. Installiert man ein Addon (z.B. S-FTP), lädt VS Code die IDE Änderungen automatisch auf den Server zurück, sobald gespeichert wird.
Aber halt immer noch in einer Subdomain. Irgendwo im Netz.

Statt dessen:

Eine eins-zu-eins-Kopie der TYPO3-Installation lokal laden - und lokal bearbeiten. Nix Download. Nix Subdomain. Und versionieren lässt sich so auch problemlos.

Zusätzlich kann man jederzeit mit einem ddev export-db (mehr braucht es nicht) den aktuellen Stand der Datenbank sichern!
Denn nicht jeder Schritt beim Upgraden des Cores und/oder Updaten der Extension muss ja auf Anhieb von Erfolg gekrönt sein - Sicher ist da sicher sicherer.

Unter Windows leidlich simpel, und die aktuellen Versionen grade von Docker (Desktop) sind auch einfach zu handhaben.

https://docs.docker.com/desktop/install/windows-install/ für Docker und https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#__tabbed_1_3 für die DDEV-Installations-Files.

Das ist bei mir jetzt schon eine ganze Weile her, und es reicht die Zeit auch bei Weitem nicht, hier näher darauf einzugehen

Man kann jeden config-Befehl (auch später problemlos) einzeln ausführen - doch warum sollte man?

"ddev config" + Parameter über die Bash (im meinem Falle die Git-Bash)

Die aktuelle für eine alte T3-10-Version config-Zeile lautete bei mir:

ddev config --php-version 7.4 --project-type=typo3 --webserver-type=apache-fpm --database mysql:5.7 --timezone Europe/Berlin --composer-version 2

Eigentlich selbst-erklärend.
Das kein beim ersten Start schon eine ganze Zeit dauern, denn es müssen ja alle Pakete erst heruntergeladen und in der lokalen Umgebung installiert werden.

Es wird auch ein Unterverzeichnis ".ddev" im aktuellen Verzeichnis ein angelegt.

Ein alter Hut für TYPO3-ler, doch kurz ein Wort, wie am besten zu verfahren ist.

Man kann natürlich die aktuellen Core-Dateien der laufenden LIVE-TYPO3-Version einfach vom Server laden - per FTP. Dauert. Muss auch nicht sein.

Denn es gibt ja auch

ddev ssh

Das funktioniert (bei mir unter Windows) leider nur im Terminal von Visual Studio Code - dort aber out-of-the-box.

Dazu auf

https://get.typo3.org/list/version/10 (oder natürlich einem anderen, zu Ihrem System passenden Pfad dort) zur aktuellen T3-Version navigieren, DOWNLOAD klicken, und das

wget --content-disposition get.typo3.org/10.4.16

in die Zwischenablage kopieren.

Auf der Shell einfügen - Return - und der Download ist ruckzuck erledigt.

Die Dateien mit tar -xf typo3_src-10.4.16.tar.gz entpacken. Schon steht ein komplettes Core-Paket zur Verfügung.

Alternativ kann man natürlich auch auf dem Live-Server das TYPO3- und das Vendor-Verzeichnis packen und dann runterladen - lokal entpacken. Geht 100mal schneller als die einzelnen Verznisse + FTP. Dazu allerdings muss man natürlich SSH-Zugriff auf den Server haben.

/typo3conf & /fileadmin sichern

Am einfachsten - und vor allem am schnellsten - sichert man die Verzeichnisse /typo3conf und /fileadmin, indem man

sie auf dem Server mit tar cf fileadmin.tar.gz fileadmin und tar cf typo3conf.tar.gz typo3conf packt,
indem man sich mit SSH auf dem Server einloggt,
die Verzeichnisse herunterlädt

um dann

über die IDE (bei mir VS Code) per ddev ssh auf die lokale Installation aufschalten

im Root-Verzeichnis der DDEV-Installation, und mittels tar -xf filedmin.tar.gz bzw typo3conf.tar.gz zu entpacken.

Das geht einfach - und ist die schnellste Möglichkeit unter Windows!

Datenbank herunterladen

Dann die Datenbank der Live-Installation über phpmyadmin komplett downloaden

mit

ddev import-db importieren: ddev import-db --file=Server-DB.sql

DDEV RESTART! zum Anlegen der additional_config.php

Wenn man wie gewohnt auch unter Windows mit Symlinks arbeiten will, geht das.

Natürlich muss man später auf dem Live-Server wieder Unix-taugliche Symlinks erstellen! (*)

Unter Windows braucht man:

Übersicht die Hilfe, die man unter Windows bei mklink /h erhält:

MKLINK [[/D] | [/H] | [/J]] Verknüpfung Ziel

        /D           Erstellt eine symbolische Verknüpfung für ein Verzeichis.
                     Standardmäßig wird eine symbolische Verknüpfung für
                     eine Datei erstellt.
        /H           Erstellt eine feste Verknüpfung anstelle einer
                     symbolischen Verknüpfung.
        /J           Erstellt eine Verzeichnisverbindung.
        Verknüpfung  Gibt den Namen für die symbolischen Verknüpfung an.
        Ziel         Gibt den Pfad (relativ oder absolut) an, auf den die
                     neue Verknüpfung verweist.

(*) Unter Unix entsprechend: Aufschalten auf den Server per SSH, dann ln -s (wobei ln für Link steht, kann man sich so gut merken).
Wobei die Syntax genau anders herum ist: ln -s Pfad-zur-Zieldatei SYMLINKS-NAME
Dort braucht es übrigens keine Unterscheidung zwischen Verzeichnissen und Dateien.

Und die Datei wird von DDEV automatisch angelegt, allerdings erst nach einem

ddev restart auf der Bash!!!

Die AdditionalConfiguration.php enthält dann den folgenden Text im Header:

/**
 * #ddev-generated: Automatically generated TYPO3 additional.php file.
 * ddev manages this file and may delete or overwrite the file unless this comment is removed.
 * It is recommended that you leave this file alone.
 */

Solange dieser Code dort unverändert steht, überschreibt DDEV bei jedem Start ALLES, was man evtl. selbst eingetragen hat!

Ist alles o.G. abgearbeitet, kann man auf der Bash ein ddev lauch ausführen.
Oder ein ddev launch typo3/, so kommt man direkt ins Backend.

Jetzt sollte die lokale Installation aus der Server-Kopie laufen.

Dann über die ddev-URL lokaleinstallation.ddev.site/typo3 ins Backend wechseln, falls kein typo3/ angehängt wurde.

Apropos "Server Kopie": Das erste, was ich mache, ist das Ändern des NAMENS der lokalen Installation der Site-Configuration! im Backend.
So läuft man nicht Gefahr, LIVE und LOKAL zu verwechseln!

Beim ersten ddev launch, um direkt das T3-Frontend aufzurufen, erscheint obige Fehlermeldung.

Hängt man an den Pfad ein /typo3 an, kommt man problemlos ins Backend - nur das Frontend läuft nicht.

Der Grund ist in diesem konkreten Falle (TYPO3-Installation) so blöd wie einfach zu beheben. Die index.php wurde nicht gefunden!
In meinem Falle ein Vertipper beim Erstellen der Symlinks (scr statt src)...
(Da das Unter-Verzeichnis /typo3 eine eigene index.php hat, läuft es dort entsprechend sofort)

Der Ideen-gebende Hinweis kam von Stackoverflow:
https://stackoverflow.com/questions/51227365/i-get-an-ngnix-403-forbidden-when-starting-ddev

Die Startseite dürfte nun funktionieren - aber auf den Sub-Seiten bekommt man die gleiche Fehlermeldung. Eventuell.

Grund: Es fehlt die .htaccess im Root-Verzeichnis.
Die wird nicht bei einer DDEV-Installation erstellt. Und wer kopiert schon das Root-Verzeichnis mit vom Server, da hat sich ja meist über die Jahre so einiges an Müll angesammelt...

Die Zeiten, als ich mich intensiv mit der .htaccess beschäftigt habe, sind schon ein Weilchen her. Unvergesslich allerdings: RealURL unter TYPO3 Vers. 3.8/4.5... ohne sich mit der .htaccess intensiv zu  beschäftigen lief dar gar nichts. Doch bei dem Thema gibt es wahrlich Berufenere als mich.

Lösung:
Einfach die .htaccess von der Serverinstallation herunterladen ins Root-Verzeichnis der DDEV-Installation.
Das sollte leidlich funktionieren, da .htaccess-Dateien durch die Provider auf maximale Kompatibilität getrimmt sind - und so eigentlich immer das Wichtigste tun, was sie sollen!

Achtung!

Der .htaccess ist ein PUNKT vorangestellt, sodass die Datei nicht sichtbar ist / sein könnte!

Dies gilt vor allem für Server, auf die man sich per FTP einloggt. Im jeweiligen FTP-Client muss man an der richtigen Stelle (abhängig vom Programm) -A eintragen,
Ähnlich für Symlinks auf Unix-Systemen: Hier ist ein "-L" nötig, um Symbolische Links als Dateien oder Verzeichnisse angezeigt zu bekommen!

Die Kombination "-LA" sorgt dafür, dass sowohl Symlinks als auch versteckte Dateien im FTP-Client angezeigt werden.

Sieht man unter Windows Dateien oder Ordner mit einem vorangestellten Punkt nicht (z.B. das .ddev-Verzeichnis) öffnet man den Datei-Explorer, geht auf Ansicht, Optionen/Ordner und Suchoptionen ändern, dann "Einstellungen für versteckte und geschützte Dateien", dann dort wieder "Ansicht"
=> und den Haken bei "Versteckte Dateien, Ordner und Laufwerke anzeigen"
=> Haken raus bei "Geschützte Systemdateien ausblenden" - den Requester quittiert man mit OK.

Indem man im Backend unter WARTUNG so ziemlich alles einmal durchgeht, inkl. Clear Persistent Database Tables, wo sich jede Menge Zeug angesammelt haben dürfte.

Nach dem erfolgreichen Download und DDEV LAUNCH werden auf der lokalen Installation zuerst alle temporären Dateien über das Backend gelöscht. Um sich keinen Müll aus der Server-Installation mit ins System zu holen mit Flush TYPO3 and PHP Cache und Clear Persistent Database Tables

... wird erst die lokale Installation auf die letzt-verfügbare Version der aktuellen Major-Version angehoben (falls noch nicht passiert)

DAVOR werden alle Extensions gecheckt:

1. Nicht benötigte werden komplett entfernt - oder zumindest deinstalliert
2. Extensions wie tt_news oder powermail sollten / können deaktiviert werden
   (Hintergrund: Bei einem Versuch scheiterte das lokale Upgrade komplett, weill erst die "news" von Georg Ringer und (nach deren Deaktivierung über die conf-Dateien) auch noch Powermail einen Fehler verursachte. Kein Konsolen-Log, kein Log-Eintrag im T3-Log, es blieb einfach hängen)

Vor dem Updaten der Extensions: Die aktuelle, lauffähige Versionsnummer merken! So hat man ein Fallback für den Fall, dass die letzt-aktuelle hier schon nicht funktioniert!

Dabei ist zu beachten, dass evtl. ein Extension-Template für die eine oder andere Extension angezogen wird!

Also: Jedes Mal testweise das Frontend aufrufen - bei jeder einzelnen Aktion im Extension-Manager, bei der man auch nur ansatzweise unsicher ist!
Es kann ja u.a. sein, dass bereits bei den minor Updates der Extensions die (eigenen) Extension-Templates Fehler produzieren / falsch referenzieren oder auf deprecated features verweisen - und so eh nicht mehr taugen. Selbst für die akutell(st)e Major-Version!

Nicht vergessen: Dabei mmer die Caches löschen!

Außerdem empfiehlt es sich, nach Deinstallieren von Extensions die

Analyze Database Structure

durchzuführen unter "Wartung" - und die empfohlenen Änderungen (Remove tables (rename with prefix) = Umbenennen in ZZZ_xyz) der Tabellennamen zu akzeptieren!

Zum Abschluss habe ich mir noch
Reset Backend User Preferences und Manage Language Packs
vorgenommen, sodass hier alles clear und up-to-date sein dürfte - für die ansonsten immer noch völlig unangetastete, lokale 1:1-Kopie.

Nachdem beim letzten Versuch ALLE NEWS verschwunden waren, und nach dem Im/Export dann ALLE KATEGORIEN, bin ich auf der Suche nach dem Fehler auf typo3.org gestoßen - dort gibt es (äußerst knappes) HowTo für Ugrades.

Und irgendwo gab es eine Erwähnung der Datenbankintegritätsprüfung... die nur deswegen ins Auge fiel, weil die Empfehlung, das über das CLI zu machen, mehr Raum einnahm als die eigentliche Erläuterung...

Beim jetzigen neuen Anlauf

führe ich das umgehend mit der noch unangetasteten 1:1-Kopie durch!

(mal schauen, was draus wird)

nach der Aktualisierung bekommt man ein grünes Feld: 5177 records from 39 tables were checked/updated. Es hat sich also ziemlich was getan. Jetzt muss nur noch das Frontend funktionieren...

Will man sich Ärger ersparen, wird ab sofort - bis zum Start der komplett angehobenen Version - das Frontend nicht mehr angerührt!

Was man da erlebt, steht (noch) hier nach im Text, doch ich überlege, es rauszuschmeißen, wenn ich daran denke (aktuell wirkt der Text in den nächsten Abschnitten dadurch noch etwas holprig).

Als hätte das System nichts mitgekriegt. Die Core-Extensions sind alle auf dem neuesten Stand...

Ein Ansatz: ddev restart - kein Effekt. Ebenso das Löschen aller Caches, inkl. Flush TYPO3 and PHP Cache.

Natürlich muss - oder sollte man, falls nicht zuvor geschehen - jetzt die Erweiterungsliste aus dem TER neu laden - und da wird einem dann schon ganz anders!

Ich nehme mir erst ein paar Erweiterungen vor, die nicht aktiv sind wie Crawler, AI-SEO-Helper usw.

Und checke alle paar Erweiterungen den Upgrade Wizard, ob Tabellen geändert wurden!

Alles Takko - bis auf "news"... hier kommt es zu einem Error in Analyze Database Structure (Bild), und im Upgrade Wizard taucht ein AJAX-Error auf...

Einige Caches gelöscht, mehr intuitiv, und plötzlich läuft der Upgrade Wizard zumindest AN, ohne AJAX-Fehler:
Set integer default value where field `tx_news_domain_model_news`.`related_links` is NULL.

Powermail verursacht keine Auffälligkeiten - wundert eingentlich auch...

DANACH läuft auch Analyze Database Structure durch! PUH!

Obowohl in der original-DB natürlich 1:1 noch voll, ist nach o.g. Schritten die Tabelle komplett leer.

Das mag damit zusammenhängen, dass die Extension für das Update deaktiviert werden musste - aber who the fuck hat dann die Tabelle geleert im Laufe des Upgrades???

... etwas Nachdenken - und die alte Gewissheit: In Datenbanken wird eigentlich NIE ETWAS GELÖSCHT! Maximal auf NULL gesetzt in der Sichtbarkeit.

Daran hält sich auch TYPO3... Tabellen werden beim Upgrade in zzz_deleted_XXX umbenannt...

Weil die NEWS-Extension deaktiviert war beim Upgrade, ist T3 davon ausgegangen: Das wird nicht mehr benötigt - und kann erstmal weg. So auch die assoziierten Tabellen - sie wurden in zzz_deleted_tx_news_XXX umbenannt in der DB.

Der grade zuvor frisch ausgeführte Wizard für category-slugs und migrate:EXT:News wird also als UNDONE markiert. Abmelden vom Backend (vorsichtshalber). Ein DDEV-Restart.

Nun werden die (nach der Re-Insatllation der NEWS-Extensieon) neu angelegten tx-newx-Tabellen GELÖSCHT!

Und die alten, mit zzz_deleted_tx_news_XXX beginnenden in tx_news_XXX zurückbenannt.

Jetzt wird der Upgrade-Wizard erneut gestartet - ein Slugs vermisst man jetzt, dafür werden Änderungen in einigen tx_news-Tabellen durchgeführt (Bild)

Danach Analyze Database Structure - und hier werden tatsächlich ebenfalls Änderungen vorgenommen

Flush TYPO3 and PHP Cache - sonstige Caches leeren... weiterhin keine Fehlermeldungen (mehr) und - die Hoffnung stirbt zuletzt. doch sie stirbt... zumindest bei den Vorschaubildern. Es ist überall nur das Symbolbild "keinBild" im Frontend.

Ich behelfe mir, indem ich den processed-Ordner neu vom Live-Server hole (jeweils mit SSH und TAR) - Kein Effekt.
ABER: Die Bilder sind weiterhin mit den News im Backend verknüpft - evtl. heißt es jetzt, die alten Einstellungen der Extension (mit eigenen Templates etc.) zu reaktivieren).

1) Die DB manipulieren - die zzz_deleted_showinpreview rück-umbenennen, die neue, leere showinpreview zuvor natürlich löschen

2) Über das Fluid-Template und tx_news-List-Modul auf Code-Ebene den showinpreview-Wert auslesen, gefunden hier https://www.emde-it-loesungen.de/techtalk/typo3/news-ausgabe-der-medien-in-views.html

Interessant - werde ich aber erst mal nicht weiter verfolgen, um mich nicht wieder irgendwo auf der (hoffentlich) Zielgerade noch zu verzetteln.

Bei den News-Tabellen ist das ja noch sprechend - aber wer weiß schon (bis vor dem Lesen dieses Artikels), dass auch die sys_file_reference betroffen sein würde...

... und wir sind ja noch nicht fertig, weiß der Geier, was da noch alles auf den Upgradenden an Überraschungen wartet...

Es sind wieder alle Vorschaubilder vorhanden - jeder entsprechende Datensatz enthält eine "1", also die Variable für "In allen Ansichten anzeigen" (statt wie zuvor der "0" für "Nur in Detailansichten anzeigen"...

... hat offensichtlich trotzdem nicht funktioniert - hier ist noch Handarbeit angesagt...

Denn eine unerwünschte (und total unformatierte) Pagination (=> blättern mit Menupunkten 1, 2, 3 etc) führt nicht zu Freudensprüngen.

Da aber wirklich alles migriert wurde, drängt sich umgehend eine Vermutung auf... und richtig:

Es wurden die Original-Powermail-Tabellen mit zzz_deleted_ tot gestellt -

Nach der Re-Aktivierung von Powermail wurden neue Tabellen erstellt - und die haben natürlich NULL Inhalt

Erster Schritt: Tabellen vergleichen

Ein Blick auf die DB der Live-Seite - ein weiterer auf die DB der DDEV-Site. Struktur der alten und neuen Tabellen von Powermal in Hinblick auf die Anzahl der Spalten.
Es zeigt sich: Die Tabellen sind zumindest schon mal in der Struktur gleich geblieben.

Das Löschen der neuen und das rück-Umbenennen der zzz_deleted sollte also zumindest in der Hinsicht keine Probleme zeitigen.

Sicherungsmäßig die neuen, leeren powermail-Tabellen in XXX umbenennen. dann die zzz_deleted_powermail vom "zzz_deleted_" befreien über den Phpmyadmin.

Checken des Upgrade-Wizard, Check TCA Migrations, Check for Broken Extensions - keine Mäkeleien - alles sauber.

Und das Powermail-Formular wird angezeigt wie zuvor.

Da kann man mal nicht meckern.

Nach dem Upgrade sind (u.a.) alle Textfelder im Backend komplett verschwunden

Eher ein Spezialfall... Ich hatte eine eigene YAML-Datei in der Sysextension RTE_CKEDITOR angelegt.
Diese muss im Verzeichnis rte_ckeditor/Configuration/RTE hinterlegt sein
Und wird über ext_localconf.php der Extension angemeldet:

Das Ganze jetzt auf Typoscript umzubiegen und extern einzubinden... wie schon mehrfach hier angedeutet: Ich will mich nicht (zu sehr) verzetteln.

Jedenfalls klappt die Änderung der ext_localconf.php inkl. der kopierten YAML-Datei: Alle Felder werden wieder angezeigt.

(Und mit TYPO3 Version 12 wird der rte_ckeditor ja wohl eh obsolet / durch den 5er ersetzt, sodass sich hier weiteren Gehirnschmalz zu investieren kaum lohnen dürfte).

Da seit dem Start einiges an Zeit ins Land gegangen ist (wie man schon allein an der Länge des Textes unschwer erkennen kann), müssen jetzt die neueren Datensätze vom Server per t3d-Export exportiert und in die lokale Version per t3d-Import eingepflegt werden.
Das kann dann schon mal dauern...

Vor dem - hoffentlich - finalen Schritt des Upgradens von PHP und MySQL wird dann noch eine Sicherung der lokalen Datenbank vorgenommen, per (Git-)Bash und dem simplen DDEV-Befehl ddev export-db:

Es empfiehlt sich, ddev debug migrate-database mysql:8.0 auf der Konsole auszuführen.

Man kann zwar auch einfach in der config.yaml im .ddev-Verzeichnis die Version auf 8.0 umstellen, und dann ein ddev restart durchführen, die erste Lösung erscheint mir aber sicherer (auch wenn das zweite schon funktioniert hatte).

NICHT

funktioniert... die Datenbank war KOMPLETT LEER nach der o.g. Migration auf MySQL 8.0...

DDEV Restart - Docker-Restart - kein Effekt.

Aber neben dem (natürlich zuvor händisch erstellten) Backup der DB gab es ja auch noch den Snapshot von DDEV. DAS zumindest hat funktioniert.

Also mit ddev import-db --file=db.sql.gz die leere Datenbank mit dem frischen Snapshot gefüllt - und das Backend ist wiederreichbar.

Das Einzige, was ich mir vorstellen kann, ist das der nicht durchgelaufene mutagen-sync-process, der mit einem Fehler abbrach, verhindert hat, dass die DB automatisch wieder hergestellt wurde.

Das oben Beschriebene ist zwar so ziemlich alles auf meinem eigenen, doch recht mühevoll angehäuften, Mist gewachen...

Aber ohne den kongenialen Wolfgang Wagner, der gerade Menschen, die sich nicht 24/7 mit TYPO3 beschäftigen, mit seiner sonoren Stimme Auftrieb gibt, wäre so einiges an Tipps wohl auf der Strecke geblieben.

So das YT-Video, das eine - nackte - T3-Installation über Docker/DDEV beschreibt:

https://www.youtube.com/watch?v=VpBFNPDcZIs

Und die YT-Serie über ein Update einer T3-8-Vers. auf 10... absolut sehenswert.
Obwohl darin - natürlich - genau alle die Fehler, über die man stolpert, nicht enthalten sind. Vor allem, weil es weder NEWS noch POWERMAIL oder gar GH_RANDOMKONTENT up-zu-graden gilt - was hier ja zu genau diesen echten Katastrophen geführt hatte.

https://www.youtube.com/watch?v=Ftg2K3HBPG4&list=PLHfxX7D3FBlJbfHhOGBcA26ilLJxCdT7y

Kontakt - Impressum - Datenschutzerklärung - Startseite