Wie man von Anfang bis Ende mit DDEV ein Typo3 Projekt einrichtet (Windows + WSL2 + Ubuntu + DDEV und Typo3 Guide)

Was du nach dem Guide können wirst

• Grundlagen über den Einsatz von Linux und Ubuntu mit WSL2 unter Windows.
• Wie du lokal eine Entwicklungsumgebung mit DDEV für Typo3 anlegen kannst.
• Wie man Typo3 installiert und erstmalig einrichtet.

Einleitung

Dieser Guide ist für die Einrichtung unter Windows 11 gedacht. Wenn du ein anderes Betriebssystem nutzt, kannst du die jeweils verlinkten Guides am Anfang der einzelnen Schritte verwenden.

Für Anfänger kann der gesamte Prozess schnell unübersichtlich wirken. Viele Anleitungen setzen bereits Kenntnisse im Umgang mit virtuellen Maschinen und der Einrichtung von Entwicklungsumgebungen voraus, anstatt bei den Grundlagen zu beginnen.

Der Einsatz von DDEV ist auf lokale Entwicklungsumgebungen beschränkt und nicht für den produktiven Betrieb vorgesehen. Um eine TYPO3-Website auf einen Produktivserver zu übertragen, muss ein separates Deployment-Verfahren verwendet werden, das in der offiziellen TYPO3-Dokumentation beschrieben ist.

Solltest du während dem Prozess irgendwo unterbrechen müssen und willst dann wieder in Ubuntu deine Arbeit fortsetzen kannst du jederzeit die PowerShell als Administrator ausführen und dann über den Befehl wsl oder wsl -d Ubuntu (falls du mehrere Subsysteme installiert hast) deine WSL-Distribution starten. Du kannst dann mit cd ~ auf dein Home Verzeichnis wechseln und dann in deinen Projektordner mit cd ordnername. Solltest du den Namen vergessen haben kannst du dir das Verzeichnis mit ls anzeigen lassen.

Schritt 1: Basis prüfen und vorbereiten.

Abhängig davon, wie viel Erfahrung bereits im Umgang mit PHP besteht, können einzelne Voraussetzungen schon erfüllt sein. Häufig ist jedoch nicht mehr klar, welche Tools bereits installiert wurden. Deshalb ist es sinnvoll, zunächst zu prüfen, welche für DDEV benötigten Technologien auf dem System vorhanden sind und welche noch ergänzt werden müssen.

Im nächsten Schritt folgt eine Liste von Befehlen, mit denen überprüft werden kann, ob die notwendigen Vorbedingungen für die Nutzung von DDEV bereits erfüllt sind.

Die Reihenfolge der Installation der jeweiligen Technologien ist hier mit Schritten sortiert und lautet grob:

WSL2 → DDEV Windows Installer (installiert auch Docker CE) → TYPO3

Falls du bisher noch nie mit DDEV oder Dock

er gearbeitet hast brauchst du nur zu Überprüfen ob die Virtualisierung im BIOS aktiviert ist.

Prüfen ob Virtualisierung im BIOS aktiviert ist:

Unter Windows prüfst du das am schnellsten im Task-Manager. Öffne den Task-Manager, gehe auf den Reiter „Leistung“ und wähle „CPU“. Dort steht „Virtualisierung: Aktiviert“ oder „Deaktiviert“.

Alternativ in PowerShell eingeben:

systeminfo

In der Ausgabe muss bei „Hyper-V-Anforderungen“ stehen, dass die Virtualisierung in der Firmware aktiviert ist:

alls da nein steht müssen wir nun die Virtualisierung im BIOS aktivieren.

Dazu kannst du entweder dieses Video-Tutorial schauen, oder unten die Anleitung befolgen:

Virtualisierung aktivieren:

Dieser Schritt unterscheidet sich je nach Windows Version.

Auf Windows 11 einfach in der Suche “Erweiterter Start eingeben”.

Diese Befinden sich unter System > Widerherstellung

Bevor du mit dem nächsten Schritt weiter machst, solltest du entweder erst den restlichen Ablauf lesen, oder ein zweites Gerät mit dem Guide oder Video Tutorial zur Hand nehmen.

1. Dann einmal auf “Jetzt neu starten” klicken.
2. Auf Problembehandlung klicken
3. Auf Erweiterte Optionen klicken
4. Dort den Menüpunkt “UEFI-Firmwareeinstellung” anklicken.
5. Dann auf “Neu starten”.
6. Im Anschluss öffnet sich dein BIOS Menü.
7. Im BIOS Menü auf “Advanced Mode (F7)” klicken.
8. Dann auf “Advanced”.
9. Dann “CPU Configuration” aufklappen.
10. Runterscrollen
    1. Bei AMD heißt der Punkt “SVM Mode” und der muss auf Enabled gestellt werden.
    2. Bei Intel lautet der Punkt “Intel Virtualization Technology” und der muss auf Enabled gestellt werden.
11. Anschließend auf EXIT
12. Save Changes und Reset und Bestätigen.

Sobald dein Rechner neu gestartet hat prüfe nochmal ob die Virtualisierung jetzt aktiviert ist:

systeminfo

In der Ausgabe muss bei „Hyper-V-Anforderungen“ stehen, dass die Virtualisierung in der Firmware aktiviert ist:

Prüfen ob WSL2 installiert ist:

wsl.exe -l -v

Wenn es nicht installiert ist erhält man folgende Meldung:

Prüfen ob Docker installiert ist

docker --version

Gibt das in deine Konsole ein. Wenn Docker nicht installiert ist erhält man folgende Meldung.

Solltest du Docker aber vorher schon installiert haben, ist es möglich das sich das einrichten mit DDEV von diesem Guide unterscheidet. Daher würde ich in diesem Fall die Dokumentation von DDEV empfehlen: https://docs.ddev.com/en/stable/

Schritt 2: WSL2 installieren und Ubuntu-Distribution einrichten.

Den Umfangreichen Guide zur WSL Installation findest du hier:

https://aka.ms/wslinstall

Du kannst theoretisch auch jede andere Linux-Distro verwenden, aber Ubuntu ist besonders anfängerfreundlich.

TLDR:

Für die Installation von WSL2 wird Windows 10 ab Version 2004 oder Windows 11 benötigt. Zusätzlich sind Administratorrechte und eine aktivierte Virtualisierung im BIOS erforderlich.

Installation von WSL2

Anschließend muss der Rechner neu gestartet werden. Während dieses Vorgangs werden die notwendigen Windows-Features aktiviert und Ubuntu als Linux-Distribution installiert.

Überprüfung

Nach der Installation kannst du mit wsl -l -v prüfen (Langform: wsl.exe --list --verbose ) , ob WSL2 korrekt installiert ist.

Distribution installieren.

Es ist möglich, dass Ubuntu nicht direkt mit installiert wurde. In dem Fall erhältst du folgende Nachricht.

Das Windows-Subsystem für Linux meldet, dass keine Distribution installiert ist. wsl --install hat dann lediglich die notwendigen Windows-Features aktiviert, aber keine Linux-Distribution aus dem Microsoft Store installiert. Das tritt häufig auf, wenn der Store-Zugriff eingeschränkt ist.

Um Ubuntu manuell zu installieren, kann die Distribution explizit angegeben werden. Danach sollte überprüft werden, ob die Installation erfolgreich war. Führe folgenden Befeh aus (Powershell mit Administratorrechten):

wsl --install Ubuntu

Beim ersten Start von Ubuntu wirst du aufgefordert, einen Linux-Benutzer sowie ein Passwort anzulegen. Schreib dir deine Daten am besten direkt auf. Das Passwort wird beim Tippen nicht angezeigt. Das ist normal.

Wenn das Anlegen des Benutzers erfolgreich war befindest du dich in der Linux-Umgebung von WSL und siehst einen Prompt wie name@DESKTOP-Zahl:/mnt/c/... . Dabei steht /mnt/c/... für das eingebundene Windows-Dateisystem. Es ist wichtig, zwischen dem Windows-Dateisystem und dem Linux-Dateisystem zu unterscheiden, da wir beim Ausführen von ddev-Befehlen im Linux-Dateisystem arbeiten werden.

Prüfen

Prüfe zum Schluss noch ob alles korrekt installiert wurde indem du wsl.exe -l -v in eine geöffnete CMD-Konsole eingibst. Falls ja sollte bei dir als Distribution Ubuntu angezeigt werden:

Wofür genau ist eigentlich WSL2?

WSL, das „Windows Subsystem for Linux“, erlaubt es, eine vollständige Linux-Umgebung direkt unter Windows zu nutzen. Entwickler können dadurch Linux-Tools, Shells und Paketmanager auf einem Windows-System verwenden.

Schritt 3: Docker Community Edition (Docker CE) und DDEV innerhalb von WSL2 installieren

Den umfangreichen Guide zur Installation von DDEV, sowie der verschiedenen Handlungsanweisungen zu unterschiedlichen Betriebssystem findest du unter folgendem Link:

https://docs.ddev.com/en/stable/users/install/ddev-installation/

TLDR: Kurzfassung für Windows 11

Auf folgender Seite kann man den DDEV Windows Installer herunterladen:

https://github.com/ddev/ddev/releases

Dort einfach die ddev_windows_amd64_installer.v1.24.10.exe herunterladen und den Zauberer starten.

Paranoides prüfen

Im nächsten Schritt prüfen wir ob DDEV korrekt installiert wurde.

Dafür geben wir in der Powershell (die du hoffentlich noch geöffnet hast) docker version ein.

Solltest du den Befehl statt dessen in CMD eingeben wird folgende Meldung erscheinen:

Der Fehler entsteht, weil dein Linux-Benutzer keine Rechte hat, mit dem Docker-Daemon zu sprechen. Standardmäßig darf nur root auf den Docker-Socket zugreifen.

root ist der Administrator-Benutzer unter Linux. Er hat vollständige Rechte auf dem System und darf alles, auch Dinge wie den Zugriff auf den Docker-Socket, die normale Benutzer standardmäßig nicht dürfen.

Führe nun zwei Befehle in der WSL Umgebung aus (also in deiner Powershell mit dem Pfad mnt/c…):

sudo usermod -aG docker $USER fügt deinen aktuellen Linux-Benutzer der Gruppe docker hinzu, sodass Docker ohne sudo genutzt werden kann.

Tipp: Falls STRG + V bei dir in der Powershell nicht funktioniert probiere es mit Rechter Maustaste.

$USER wird automatisch durch deinen aktuell angemeldeten Linux-Benutzer ersetzt, und sudo fragt dich nach dem Passwort, das du beim Anlegen des Benutzers in Ubuntu vergeben hast. Gruppenmitgliedschaft aktivieren

Als nächstes verwendest du den Befehl newgrp docker was deine Gruppenmitgliedschaft sofort aktiviert, ohne dass du WSL neu starten musst.

Mit ddev version und docker version kannst du nun prüfen, ob DDEV korrekt installiert ist und erfolgreich mit dem Docker-Daemon kommunizieren kann.

Schritt 4: DDEV verwenden

Führe alle DDEV-Befehle ausschließlich innerhalb von WSL2 aus, zum Beispiel im Ubuntu-Terminal. Wechsle dort in dein Projektverzeichnis im Linux-Dateisystem und nutze DDEV nur an dieser Stelle. Verwende PowerShell, CMD oder Git Bash unter Windows nicht für DDEV, da diese Umgebungen nicht zuverlässig mit der Docker- und DDEV-Umgebung in WSL2 arbeiten.

Woran erkenne ich ob ich im Ubunto Terminal bin oder im Linux-Dateisystem arbeite?

Du erkennst das Ubuntu-WSL-Terminal daran, dass dein Prompt typischerweise so aussieht: <user>@<hostname>:~$. Das ~ steht für dein Home-Verzeichnis unter Linux.

Ob du im Linux-Dateisystem bist, erkennst du am Pfad. Linux-Pfade beginnen mit /, zum Beispiel /home/<user>/projekt. Wenn dein Pfad mit /mnt/c/ beginnt, arbeitest du gerade im Windows-Dateisystem, also z. B. C:\\ aber aus Linux heraus.

Prüfen kannst du das direkt mit diesen Befehlen.

pwd

Der Befehl pwd gibt das aktuelle Arbeitsverzeichnis im Terminal aus.

Wenn die Ausgabe mit /home/ beginnt, bist du im Linux-Dateisystem. Wenn sie mit /mnt/c/ beginnt, bist du im Windows-Dateisystem. Solltest du im Windows-Dateisystem seinkannst du ganz einfach mit cd ~ ins Home-Verzeichnis von Linux.

Schritt 5: Typo3 mit DDEV installieren

Zum Installieren von TYPO3 mit DDEV gibt es auf folgender Seite einen Quick Start Guide. Was dort jedoch im Quickstart fehlt ist, dass wir das Projekt im Linux Filesystem anlegen wollen.

1. Ins Linux Filesystem wechseln

cd ~ wechselt in dein Linux-Home-Verzeichnis, damit du das Projekt im WSL-Linux-Dateisystem anlegst und nicht unter /mnt/c/..., was für DDEV/TYPO3 mit Docker langsamer ist und häufiger Permission-Probleme macht. Das leere ~$ zeigt, dass du dich jetzt im Home-Verzeichnis deines Linux-Benutzers befindest.

2. Projektordner anlegen

Lege einen Ordner an. So bleibt dein Home-Verzeichnis sauber, und du hast alle Projekte an einer Stelle, zum Beispiel ~/projects.
mkdir -p ~/projects erstellt den Ordner projects in deinem Home-Verzeichnis, falls er noch nicht existiert. Mit cd ~/projects wechselst du in diesen Ordner, damit du dort deine Entwicklungsprojektordner anlegen kannst.

3. Typo3 Projektordner anlegen

mkdir my_project && cd my_project 

erstellt den Ordner my_project und der Zusatz && cd my_project wechselt direkt in diesen Ordner, damit alle folgenden Befehle im Projektverzeichnis ausgeführt werden.

4. DDEV-Projekt initialisieren

ddev config --php-version 8.4 --docroot public --project-type typo3

legt die DDEV-Konfiguration für dein Projekt an, setzt PHP 8.4, definiert

public als Web-Root (Document Root) und wählt den Projekttyp TYPO3, damit DDEV passende Defaults nutzt.

5. DDEV-Umgebung starten

ddev start 

startet die Container für das Projekt (Webserver, Datenbank und weitere benötigte Dienste), sodass du eine laufende Entwicklungsumgebung hast. Es ist möglich das DDEV dich fragt ob sie anonyme Statistiken senden darf, du kannst selbst entscheiden ob du Y für yes oder n für no verwendet. (Generell ist es für Anfänger wichtig sich die Konsoleninhalte durchzulesen oder zumindest zu überfliegen).

6. TYPO3 per Composer installieren

ddev composer create-project "typo3/cms-base-distribution:^13" 

lädt TYPO3 13 als Basis-Distribution per Composer in dein Projekt, wobei Composer innerhalb der DDEV-Umgebung ausgeführt wird.

7. TYPO3 per CLI einrichten.

ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db 

führt das TYPO3-Setup über die Kommandozeile aus und trägt dabei die Datenbankverbindung direkt ein, wobei

--host=db den Datenbank-Container in DDEVs internem Docker-Netzwerk adressiert, --port=3306 den Standard-MySQL-Port nutzt und --dbname=db --username=db --password=db die von DDEV vorgegebenen Standard-Zugangsdaten für die Projekt-Datenbank verwendet.

Während des Setups fragt TYPO3 interaktiv nach dem Datenbank-Host. Steht dort [default:db], kannst du einfach Enter drücken, da db der korrekte Hostname für die von DDEV bereitgestellte Datenbank ist.

Schritt 6: Typo 3 Setup

Jetzt wirst du zu verschiedenen Dingen aufgefordert:

Enter the database "host" [default: db] ? da gibst du einfach db als default an und drückst auf Enter. Anschließend wirst du nach dem Admin Username gefragt, gib hier einfach einen frei wählbaren Benutzernamen ein, zum Beispiel admin. Dann wählst du ein Passwort und deine Admin Email Adresse. Bei Give your project a name [default: New TYPO3 Project] ? kannst du einen beliebigen Projektnamen wählen z.B. typo3-project. Bei Create a basic site? Please enter a URL [default: no] gibst du einfach http://my-project.ddev.site ein.

Wenn alles korrekt gelaufen ist solltest du folgende Meldung in der Konsole sehen:

✓ Congratulations – TYPO3 Setup is done.

Schritt 7: Backend im Browser öffnen.

ddev launch /typo3/ öffnet die TYPO3-Backend-Login-Seite im Browser über die von DDEV bereitgestellte Projekt-URL.

Falls du in deinem Browser über eine unsichere Verbindung gewarnt wirst kannst du einfach auf Weiter zur Website klicken. Im Anschluss müsste sich bei dir der Login Bereich zum Backend öffnen:

Hier gibst du genau die Zugangsdaten ein, die du beim typo3 setup in der Konsole festgelegt hast. Wenn alles gut lief befindest du dich nun im Typo3 “Backend”.

Troubleshooting

Es ist möglich das du beim eintippen des Passworts einen Schreibfehler hattest und jetzt nicht in den Adminbereich rein kommst. Die einfachste Option ist es ein neues Typo3 Projekt anzulegen und das Setup nochmal durchzuführen.