Wie man TYPO3-Daten von Kunden mittels DDEV-Providers abruft

19. März 2025 |Jochen Roth

Beitragsbild für Artikel How to fetch a customer's TYPO3 data with a DDEV custom provider

Um das Problem eines Kunden zu reproduzieren, müssen dessen TYPO3 Daten oft in eine Entwicklungs- oder Testumgebung repliziert werden. Wenn du nicht über einen strukturierten, konsistenten Prozess verfügst, kann die Datenreplikation fehlschlagen oder inkonsistente Ergebnisse liefern.

Bei b13 nutzen wir DDEV unter anderem als sichere und bequeme Möglichkeit, um Produktionsinhalte aus einer entfernten TYPO3-Instanz in unsere lokale Umgebung zu ziehen. Auf diese Weise können wir die Probleme unserer Kunden beheben und Änderungen in ihrem Namen vornehmen.

In diesem Artikel erklären wir, wie man einen konsistenten Prozess für den Abruf von TYPO3-Daten von Kunden mit benutzerdefinierten DDEV-Providern einrichtet.

Was sind DDEV-Provider?

DDEV ist ein Werkzeug, mit dem innerhalb von Minuten eine lokale PHP-Entwicklungsumgebung in einem Docker-Container gestartet werden kann. Für eine einfache Integration mit Hosting-Anbietern enthält DDEV ein Konzept für das Pulling und Pushing der Datenbank und der benutzergenerierten Dateien von und zu einem Upstream-Anbieter. Das Schöne am DDEV-Provider-Konzept ist, dass du eigene Provider definieren kannst. Du kannst deine Kunden als „Provider“ einrichten und dann ihre Datenbank und benutzerdefinierten Dateien in eine lokale DDEV-Umgebung ziehen.

Mit einem benutzerdefinierten DDEV-Anbieter kannst du einen standardisierten, wiederholbaren Prozess für das Abrufen von Produktionsinhalten einrichten. Alle Dateien, die an der Einrichtung beteiligt sind, können unter Versionskontrolle gestellt werden und so leicht mit anderen geteilt werden.

Durch die Möglichkeit, Produktionsinhalte abzurufen, kannst du deren Umgebung spiegeln, um Fehler zu beheben oder Änderungen vorzunehmen.

Diese Anleitung behandelt nur das Abrufen von Daten. In der DDEV-Dokumentation zur Integration von Hosting-Providern wird empfohlen, Änderungen nicht direkt an einen Provider weiterzugeben, um zu vermeiden, dass die Upstream-Site beschädigt wird.

Du musst auch beachten, dass das Pull/Push-Konzept von DDEV nicht das Pullen oder Pushen des Code-Teils des CMS beinhaltet. Hierfür benötigst du in der Regel eine Quellcode-Verwaltung (Git, Mercurial o.ä.) und einen Workflow für die Bereitstellung.

Wie funktionieren DDEV Provider?

Aus der Sicht eines Benutzers besteht ein DDEV-Anbieter aus zwei Teilen:

Einem Provider-Recipe, das Befehle für Authentifizierungs-, Pull- und Push-Aktivitäten definiert.
Hooks, die durch Ereignisse wie Pre-Pull oder Post-Pull ausgelöst werden.

Provider-„Rezepte“ verwenden eine Reihe von vordefinierten Befehlsstrophen, die du auf jede beliebige Weise einrichten kannst. Der Befehl „auth_command“ gibt beispielsweise an, wie die Authentifizierung gegenüber einem Server erfolgen soll, der Befehl „db_pull_command“ und der Befehl „files_import_command“ geben an, wie Datenbankinhalte und Dateien vom Server geholt werden sollen.

Wenn der Benutzer ddev pull <provider> oder ddev push <provider> aufruft, benutzt DDEV die entsprechende Datei „.ddev/providers/<provider>.yaml“, um die auszuführenden Aktionen zu bestimmen.

Zwei Bemerkungen zu den Befehlen:

DDEV pull verwendet die im Skript definierten Befehle. Falls kein „db_import_command“ definiert ist, versucht DDEV automatisch, die Datei „.ddev/.downloads/db.sql.gz“ in die Standarddatenbank „db“ zu importieren.
DDEV pull führt die Befehle in einer vordefinierten Reihenfolge aus, unabhängig von der Reihenfolge, in der sie in der Recipe definiert sind.

Eine Liste der verfügbaren Befehlsstrophen findet sich unter Hosting Provider Integration in der DDEV-Dokumentation.

Wie erstellt man einen DDEV Provider?

In diesem Abschnitt gehen wir einen realen Anwendungsfall durch, um zu zeigen, wie man einen DDEV-Provider erstellt.

Bei b13 untersuchen wir häufig TYPO3-Datenbanken und Dateien im Verzeichnis „fileadmin“ von unseren Kunden. Um sicherzustellen, dass wir einen konsistenten, wiederholbaren und gemeinsam nutzbaren Prozess haben, haben wir einen DDEV-Provider eingerichtet, um Datenbank- und Datei-Assets aus der Live-Umgebung eines Kunden zu ziehen.

Schritt 1: Ein Provider-Recipe schreiben

Der erste Schritt besteht darin, das Provider-„Recipe“ zu definieren, d. h. eine Reihe von Befehlen, die für den Zugriff auf die Kundenumgebung und das Abrufen der Daten erforderlich sind.

Erstelle eine YAML-Datei in „.ddev/providers/“. Der DDEV-Pull-Befehl verwendet den Dateinamen, daher sollte der Name kurz gehalten werden. In dieser Anleitung werden wir den Namen „live“ verwenden.

Öffne „live.yaml“ in deinem bevorzugten Editor. Die Datei enthält mehrere Einstellungen, die wir nacheinander durchgehen werden.

Informationen zur Umgebung

Dieser Teil ist optional, aber sehr empfehlenswert. Anstatt die Serverinformationen in jedem Befehl fest zu codieren, kannst du wiederverwendbare Umgebungsvariablen konfigurieren. Wenn du die Konfiguration für eine andere Umgebung wiederverwenden willst, musst du nur die Variablen ändern. Der Rest der Konfiguration bleibt unverändert.

Für die Live-Umgebung setzen wir eine „Server“-Variable, die den SSH-formatierten Benutzer- und Hostnamen des Servers enthält, und eine „ProjectRoot“-Variable, die den Pfad zur TYPO3-Instanz enthält.

1
2
3

environment_variables:
  server: <user>@<host>
  projectRoot: /path/to/typo3

Authentifizierung

Eine gängige Methode für den Zugriff auf einen entfernten Server ist SSH. In dieser Anleitung gehen wir davon aus, dass du bereits eine SSH-Authentifizierung mit dem Server des Kunden eingerichtet hast; das heißt, du hast einen privaten SSH-Schlüssel in „~/.ssh/“ hinterlegt und den entsprechenden öffentlichen Schlüssel auf dem Server.

Erstelle eine auth_command-Einstellung mit einem Befehlseintrag, der ssh-add -l aufruft, um zu testen, ob der SSH-Agent private Schlüssel enthält.

Der Befehl ssh-add -l listet die Fingerprints der verfügbaren Schlüssel auf. Wenn es keine Fingerprints zum Auflisten gibt, gibt der Befehl einen Exit-Wert ungleich Null zurück, den wir hier verwenden, um eine Fehlermeldung auszulösen, die die Ausführung von ddev auth ssh empfiehlt.

Der Aufruf von ddev auth ssh kopiert deine lokalen SSH-Schlüssel in den Web-Container, so dass die Schlüssel innerhalb des Containers nutzbar werden. Beachte, dass die kopierten SSH-Schlüssel nicht dauerhaft im Web-Container gespeichert werden. Daher solltest du sicherstellen, dass du ddev auth ssh ausführst, nachdem du den Web-Container erstellt oder neu erstellt hast.

1
2
3

auth_command:
  command: |
    ssh-add -l >/dev/null || ( echo "Please 'ddev auth ssh' before running this command." && exit 1 )

Pull der Datenbank

Jetzt sind wir bereit, die Datenbank zu ziehen. DDEV erwartet von deinem Skript in „db_pull_command“, dass es einen Datenbank-Dump in „.ddev/.downloads/db.sql.gz“ herunterlädt. Von hier aus extrahiert und importiert DDEV die Daten in die lokale TYPO3-Datenbank.

Das Skript macht aus zwei Gründen ausgiebig Gebrauch von der MySQL-Option --ignore-table:

Erstens wollen wir vermeiden, sensible Kundendaten zu extrahieren.
Zweitens wollen wir die Größe des Downloads verringern, indem wir Tabellen ausschließen, die wir entweder nicht benötigen oder lokal neu erstellen können.

Beachte, wie dieses Skript die Umgebungsvariablen „server“ und „projectRoot“ verwendet, die wir zuvor definiert haben.

Aus dem Verzeichnis „projectRoot“ bezieht der Pull-Befehl die Datei „.env“, die die Umgebungsvariablen enthält, die beim Aufruf von mysqldump verwendet werden. Dot-env-Dateien sind ein bequemer Weg, um sensible Daten wie die Anmeldedaten für die Datenbank in eine Prozessumgebung einzubringen. Bei b13 verwenden wir „.env“-Dateien zusammen mit dem Paket helhum/dotenv-connector, um die Anmeldedaten zu verwalten. Alternativ kannst du die Anmeldedaten auch aus der Datei „settings.php“ abrufen oder dich mit einer bestehenden Lösung zur Verwaltung von Geheimnissen verbinden.

..  code-block:: yaml
    db_pull_command:
      command: |
        ssh "${server}" 'source '${projectRoot}/.env'; MYSQL_PWD=$TYPO3_DB_PASSWORD mysqldump --no-tablespaces \
          --ignore-table=$TYPO3_DB_DATABASE.sys_log \
          --ignore-table=$TYPO3_DB_DATABASE.fe_sessions \
          --ignore-table=$TYPO3_DB_DATABASE.be_sessions \
          --ignore-table=$TYPO3_DB_DATABASE.cache_pages \
          --ignore-table=$TYPO3_DB_DATABASE.sys_history \
          --ignore-table=$TYPO3_DB_DATABASE.sys_refindex \
          --ignore-table=$TYPO3_DB_DATABASE.sys_messenger_messages \
          -u $TYPO3_DB_USERNAME $TYPO3_DB_DATABASE -h $TYPO3_DB_HOST | gzip -9 -c' > .ddev/.downloads/db.sql.gz
      service: web

Wir müssen kein Skript für die „db_import_command“ stanza schreiben, um den heruntergeladenen Datenbank-Dump zu extrahieren und zu importieren. ddev pull bietet ein Standardverhalten, das sich um diesen Schritt kümmert.

Importieren von Dateien aus „fileadmin“

Um das Setup des Kunden zu replizieren, benötigen wir die Dateien, die sich in „<projectRoot>/public/fileadmin“ befinden. Mit der Stanza files_import_command können wir ein „rsync“-Skript einrichten, das die Dateien aus dem entfernten „fileadmin“-Verzeichnis in unser lokales „fileadmin“-Verzeichnis holt.

files_import_command:
  command: |
    rsync --ignore-existing -rvz --exclude='_processed_' "${server}":"${projectRoot}/public/fileadmin/*" public/fileadmin/
  service: web

Schritt 2: Setup für Post-Pull Hooks

Unser Skript ist jetzt vollständig. Wenn wir ddev pull live aufrufen, führt DDEV die Befehle in dieser Reihenfolge aus:

Festlegen der Umgebungsvariablen
Alle Authentifizierungsbefehle (vergiss nicht, ddev auth ssh auszuführen)
Alle Pull-Befehle
Alle Importbefehle

Wir können die „pull“-Aktion jedoch noch weiter anpassen. ddev pull-Befehle lösen Pre- und Post-Execution-Hooks aus, die wir für die Vorbereitung oder Aufräumarbeiten nutzen können.

Hooks sind eine allgemeine Funktion von DDEV und daher nicht Teil unseres Pull-Skripts. Sie sind vielmehr in der zentralen Datei „.ddev/config.yaml“ definiert. Die Hooks werden für jedes Provider-Skript ausgelöst, das du in „.ddev/providers“ definiert hast, sodass du hier nur Aktionen platzieren solltest, die für eines deiner Skripte gültig und erforderlich sind.

Unten ist die Konfiguration für einen Post-Pull-Hook, der für unser Live-Skript verwendet wird. Jeder Hook besteht aus einer Liste von Befehlen, die der Reihe nach ausgeführt werden.

Der erste Post-Pull-Befehl stellt sicher, dass alle für die Einrichtung des Kunden erforderlichen Tabellen in der lokalen Umgebung vorhanden sind.
Der zweite Befehl fügt der Einfachheit halber einen Standard-Administratorbenutzer hinzu.

hooks:
  post-pull:
    - exec: vendor/bin/typo3 extension:setup
    - exec: TYPO3_BE_USER_NAME=admin TYPO3_BE_USER_PASSWORD=Password.1 TYPO3_BE_USER_ADMIN=1 ./vendor/bin/typo3 backend:user:create --no-interaction

Jetzt kannst du die TYPO3 Umgebung deines Kunden replizieren.

Verwendung des Providers

Mit dem Provider-Rezept und den Hooks an Ort und Stelle muss nur noch dieser Befehl ausgeführt werden, um eine replizierte DB und ein fileadmin-Verzeichnis in Ihrem lokalen ddev-Projekt zu erhalten.

ddev pull live

Wenn du den Befehl für ein neu erstelltes DDEV-Projekt ausführst, wird ddev pull zuerst die Umgebung starten - erwarte ein paar Docker-Pulls und andere Aktivitäten. Handelt es sich um ein bestehendes Projekt, wird das Recipe in der zuvor beschriebenen Reihenfolge ausgeführt: Umgebungsvariablen setzen, Authentifizierung durchführen, alle Pull-Befehle ausführen und schließlich alle Import-Befehle ausführen. Pre- und Post-Hooks werden wie definiert ausgelöst.

Als Ergebnis steht nun eine lokale Umgebung mit den Daten deines Kunden zur Verfügung.

Wenn du aus irgendeinem Grund bestimmte Schritte des Pull-Prozesses überspringen möchtest, kannst du dies über Kommandozeilen-Flags tun:

-y überspringt den Schritt der Bestätigung
--skip-db überspringt db_pull_command
--skip-files überspringt file_pull_command (wird hier nicht verwendet)
--skip-import überspringt file_import_command

Debugging

Manchmal geht etwas schief, und deine Befehle werden nicht wie vorgesehen ausgeführt. Kein Grund zur Sorge - DDEV hat für alles gesorgt. Hier sind drei Tipps zur Fehlerbehebung:

Verwende set -x, um das Output Level zu erhöhen.
Durch Hinzufügen eines set -x-Befehls zu einer der Skriptbefehle kannst du die Bash-Debugging-Ausgabe aktivieren. Ein Beispiel dafür findet sich im rsync-Provider-Beispiel im Repository ddev/pkg auf GitHub.
Außerdem kannst du die erhöhte Befehlsausgabe nutzen, indem du das entsprechende Command-Flag setzt.
Du kannst Befehle überspringen, um dich auf bestimmte Befehle zu konzentrieren, indem du die im vorherigen Abschnitt aufgeführten --skip-*-Flags verwendest.
Auf diese Weise lässt sich z. B. der Importschritt für bereits gezogene Dateien testen, ohne dass ein kostspieliger Pull-Befehl erneut ausgeführt werden muss.

Um einzelne Befehle innerhalb des DDEV-Webcontainers zu testen, verwendest du den Befehl ddev ssh. DDEV-Provider-Befehle werden im Web-Container ausgeführt, sofern nicht anders konfiguriert.

Fazit

Die Implementierung eines benutzerdefinierten DDEV-Providers ist ein benutzerfreundlicher und sicherer Ansatz zur Übertragung von Live-Kundendaten von einer entfernten TYPO3-Instanz in eine lokale Entwicklungsumgebung.

Ohne einen benutzerdefinierten DDEV-Provider könnte der Prozess des Abrufs von Kundendaten anfällig, unsicher und schwer zu pflegen sein. Das DDEV-Provider-Konzept ermöglicht es dir, einen Prozess einzurichten, der standardisiert, wiederholbar und gemeinsam nutzbar ist, um reproduzierbare Ergebnisse innerhalb des Teams zu erzielen.

Du brauchst nur ein DDEV-Provider-Rezept zu erstellen und es zur Wiederverwendung in ein Git-Repository einzuchecken.

Wenn Du mit der Einrichtung deines Projekts beginnen möchtest, nimm Kontakt mit uns auf. Wir helfen dir, eine Deployment-Pipeline und umgebungsspezifischen Code in deinem TYPO3-Projekt einzurichten.

Meld dich bei uns.