Diese Anleitung ist für die Installation des CONTENIDO CMS auf einem Windows Entwicklungsrechner mit WSL, Docker & DDEV.

Docker, DDEV & WSL

Das Entwickeln von Webanwendungen unter Windows funktioniert sehr gut, ich arbeite seit Jahren mit einem XAMPP-Stack, habe es so angepasst, dass ich je nach Projekt zwischen verschiedenen PHP Versionen (PHP 5, PHP 7 & PHP 8) wechseln kann. Sofern man einige Punkte beachtet, z. B. das unterschiedliche Verhalten zwischen Windows und Linux bei der Groß- und Kleinschreibung von Dateien, kann man unter Windows entwickeln und die Web-Anwendung läuft später problemlos auf einem Linux-Server.

Braucht man aber Funktionalität oder eine Software, die nur unter Linux verfügbar ist oder man arbeitet mit verschiedenen Diensten, die wiederum ihre eigene Umgebung benötigen, welche nicht kompatibel mit der Entwicklungsumgebung ist, kommt man nicht um den Einsatz einer virtualisierten Entwicklungsumgebung herum. Docker bietet hier eine Lösung, mit der man Containeranwendungen erstellen kann, jede Anwendung läuft dabei in seinem eigenen Container.

DDEV ist eine Open-Source-Software, mit der man in kurzer Zeit eine Entwicklungsumgebung für PHP, Python und Node.js erstellen kann. Mit DDEV erstellte Umgebungen sind flexibel erweiterbar, lassen sich für die gemeinsame Nutzung mit anderen Entwicklern versionieren, sodass man einen Docker-Workflow ohne Docker-Erfahrung nutzen kann.

Mit dem Microsoft Windows Subsystem für Linux (WSL) können Benutzer Linux-Programme direkt auf dem Windows-Kernel starten. WSL ist ab Windows 10 verfügbar. Somit ist WSL dafür prädestiniert, als Entwicklungsumgebung unter Windows eingesetzt zu werden.

Mit WSL, Docker & DDEV hat man eine Möglichkeit, schnell und effektiv eine eigene Entwicklungsumgebung pro Projekt aufzusetzen. Jedes Projekt besteht somit aus einem oder mehreren Containern, die in ihrer eigenen Umgebung laufen. Um Performanceproblemen vorzubeugen, sollte man direkt im WSL arbeiten, ein im WSL-Dateisystem gespeichertes Projekt direkt in der IDE öffnen.

Benötigte Software bei Bedarf installieren

WSL

Auf dem Windowsrechner sollte man das Windows-Subsystem für Linux (WSL) installieren, z. B. mit der Ubuntu-Distribution, die Anleitung dafür gibt es auf der Microsoft-Seite.

Docker und DDEV

Docker und DDEV müssen auf Ihrem lokalen Rechner (idealerweise in WSL) installiert sein, bevor CONTENIDO installiert werden kann.

Die Anleitung zur Installation von Docker gibt es auf docker.com und die Anleitung zur Installation von DDEV gibt es auf DDEV Docs.

Ich habe für mich entschieden, Docker und DDEV direkt in WSL zu installieren, also mit Docker und DDEV in WSL zu arbeiten. Diese Vorgehensweise ist unter DDEV Docs DDEV Installation > WSL2 + Docker CE Inside Install Script beschrieben, siehe Punkt 2. In an administrative PowerShell run this PowerShell script by executing:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/ddev/ddev/master/scripts/install_ddev_wsl2_docker_inside.ps1'))

Windows-Terminal

Die Installation von Windows-Terminal ist zwar optional, aber Windows-Terminal ist eine moderne und sehr gute Terminalanwendung, mit der man verschiedene Befehlszeilentools und Shells benutzen kann, unter anderem, Eingabeaufforderung, PowerShell und WSL, usw. Windows-Terminal kann man sich vom Microsoft-Store beziehen.

Git

Git wird benötigt, um den Quellcode von CONTENIDO aus dem GitHub-Repository auszuchecken. Dies ist optional, man kann auch das Zip-Archiv herunterladen und in das Projektverzeichnis entpacken. Will man aber nach der hier beschriebenen Anleitung gehen, braucht man git.

Auch wenn Git auf dem Windows-System installiert ist, wird es zusätzlich in WSL benötigt.

In der Regel ist Git in den meisten Linux-Distributionen vorinstalliert, falls es in WSL nicht vorhanden ist, das lässt sich mit dem Befehl git version in WSL prüfen, gibt es eine Anleitung zur Installation von Git unter WSL auf der Seite Get started using Git on Windows Subsystem for Linux.

Haupt-Projektordner in WSL erstellen

Hat man alle nötigen Voraussetzungen erfüllt, also WSL, Docker, DDEV & Git ist installiert und eingerichtet, kann man mit dem Einrichten des Projektordners in WSL beginnen. Der Haupt-Projektordner kann in beliebigem Verzeichnis erstellt werden, ich bevorzuge es im Home-Verzeichnis des Benutzers zu machen.

Zugriff auf das WSL-Dateisystem:

Hat man Windows-Terminal installiert, kann man Windows-Terminal starten und einen neuen Tab in WSL öffnen. Windows-Terminal sollte automatisch erkennen, dass auf dem System WSL installiert ist und zeigt dabei als Option den Namen der unter WSL installierten Linux-Distribution an, z. B. Ubuntu.

Zum Home-Verzeichnis wechseln:

Sofern man nicht in seinem Benutzerverzeichnis ist, mit folgendem Befehl zum Benutzerverzeichnis wechseln:

cd ~

Haupt-Projektordner erstellen:

Im Benutzerverzeichnis mit folgendem Befehl den Haupt-Projektordner erstellen:

mkdir projects

Der Name des Haupt-Projektordners kann beliebig vergeben werden, z. B. projekte.

CONTENIDO Sourcen auschecken

In das zuvor erstellte Projektverzeichnis wechseln:

cd projects

Den Projektordner für CONTENIDO erstellen und in den Projektordner wechseln:

mkdir contenido

cd contenido

Der Name des Projektordners ist wichtig, das dieser später als Hostname von DDEV verwendet wird, das Format für Hostname ist {projektordner}.ddev.site, in diesem Fall also contenido.ddev.site.

Mit folgendem Befehl die CONTENIDO Sourcen direkt in den Projektordner auschecken:

git clone https://github.com/CONTENIDO/CONTENIDO.git ./

DDEV CONTENIDO Projekt aufsetzen

DDEV Konfiguration anlegen

Mit folgendem Befehl die DDEV Konfiguration anlegen:

ddev config 
    --mutagen-enabled 
    --php-version 8.1 
    --database mariadb:10.7 
    --project-type php 
    --timezone Europe/Berlin 
    --webimage-extra-packages="graphicsmagick" 
    --webserver-type apache-fpm 
    --docroot . 
    --composer-version 2

Beschreibung der Konfigurationsoptionen:

  • --mutagen-enabled: Mutagen aktivieren (ist in der Regel global aktiv), das sorgt für eine bessere Performanz
  • --php-version 8.1: PHP mit Version 8.1 verwenden
  • --database mariadb:10.7: Als Datenbank MariaDB 10.7 verwenden
  • --project-type php: Projekttyp ist PHP
  • --timezone Europe/Berlin: Die Zeitzone auf Europe/Berlin setzen
  • --webimage-extra-packages="graphicsmagick": Zusätzlich Graphicsmagick installieren
  • --webserver-type apache-fpm: Als Webserver Apache verwenden
  • --docroot .: Als DocumentRoot das aktuelle Verzeichnis setzen, also ~/projects/contenido
  • --composer-version 2: Composer in der Version 2 verwenden

Weitere DDEV Konfigurationsoptionen und deren detaillierte Beschreibung gibt es unter DDEV Docs - Config Options

Die DDEV Konfiguration wird im Ordner .ddev als config.yaml angelegt. Diese Konfigurationsdatei kann auch ins Git-Repository committed werden, damit andere Team-Mitglieder daraus die gleiche Entwicklungsumgebung für das CONTENIDO Projekt aufzusetzen können.

PHP Abhängigkeiten installieren

Mit folgendem Befehl die in der composer.json definierten PHP Abhängigkeiten installieren:

ddev composer install

Da wir in einem Container arbeiten, sind Befehle immer mit einem vorangestellten ddev {befehl} auszuführen, z. B. ddev composer install, ddev npm install, usw. Näheres zur Verwendung der DDEV CLI gibt es unter DDEV Docs - Using the ddev Command.

Während der Installation wird auch versucht, einen Eintrag in der hosts-Datei zu erstellen, damit die installierte CONTENIDO-Seite auch unter dem Hostnamen contenido.ddev.site erreichbar ist. Sollte dies nicht funktionieren, kann man den Eintrag in der hosts-Datei manuell anlegen.

Dafür den Editor in Windows mit Adminberechtigung öffnen (als Administrator ausführen), im Editor die hosts-Datei (C:\Windows\System32\drivers\etc\hosts) öffnen folgende Zeile hinzufügen und speichern.

127.0.0.1 localhost contenido.ddev.site

Sollte die Installation stehengeblieben sein, kann man den Prozess mit der Tastaturkombination Strg+X beenden und durch Eingabe von ddev composer install neu starten.

Setzen der Verzeichnis- und Dateiberechtigungen

Der Webserver, der der die CONTENIDO Seiten ausliefert, benötigt gewisse Rechte auf diverse Verzeichnisse- und Dateien. Mit folgenden Befehlen kann man diese setzen:

ddev exec find data -type d -print0 | xargs -0 chmod 755
ddev exec find data -type f -print0 | xargs -0 chmod 664

ddev exec find cms/cache -type d -print0 | xargs -0 chmod 755
ddev exec find cms/cache -type f -print0 | xargs -0 chmod 664

ddev exec find cms/css -type d -print0 | xargs -0 chmod 755
ddev exec find cms/css -type f -print0 | xargs -0 chmod 664

ddev exec find cms/data -type d -print0 | xargs -0 chmod 755
ddev exec find cms/data -type f -print0 | xargs -0 chmod 664

ddev exec find cms/js -type d -print0 | xargs -0 chmod 755
ddev exec find cms/js -type f -print0 | xargs -0 chmod 664

ddev exec find cms/templates -type d -print0 | xargs -0 chmod 755
ddev exec find cms/templates -type f -print0 | xargs -0 chmod 664

ddev exec find cms/upload -type d -print0 | xargs -0 chmod 755
ddev exec find cms/upload -type f -print0 | xargs -0 chmod 664

ddev exec find contenido/tools -type f -print0 | xargs -0 chmod 755

CONTENIDO installieren

CONTENIDO mit der URL zum Setup im Browser öffnen:

ddev launch setup/

Dieser Befehl öffnet die URL contenido.ddev.site/setup im Browser, in der man das Setup durchführen kann.

Die Verbindungsdaten für die Datenbank sind vorgegeben und lauten:

  • Host: db
  • Benutzername: db
  • Passwort: db
  • Datenbank: db

Wichtig:

Achtet darauf, dass die Web-Pfade von CONTENIDO und dem Mandanten mit SSL (https) angegeben werden, falls nicht, kann es sein, dass Bilder, CSS- und JavaScript-Dateien im Frontend nicht geladen werden.

Ist die Installation abgeschlossen, kann man sich im CONTENIDO Backend anmelden und/oder das Frontend aufrufen.

Entwickeln in WSL

Wie zuvor erwähnt, sollte man alles im WSL-Dateisystem machen, das gilt auch für die IDEs, mit denen man an den Projekt-Sourcen arbeiten möchte. Im Folgenden eine kurze Beschreibung für Visual Studio Code und PhpStorm.

Visual Studio Code:

Das Öffnen des Projekts in Visual Studio Code ist recht einfach. Man öffnet einen Terminal, wechselt zum Projektverzeichnis (cd ~/projects/contenido) und gibt folgenden Befehl ein:

code .

Bei Bedarf wird ein Plugin für die IDE installiert und das Projekt in der IDE geöffnet.

PhpStorm:

  • PhpStorm öffnen
  • Auf "Datei > Neues Projekt aus existierenden Dateien" klicken
  • Im nächsten Fenster das passende Szenario wählen
  • Im Fenster zur Auswahl des Verzeichnisses, das Verzeichnis zum Projekt unter WSL wählen, z. B. \\wsl$\Ubuntu\home\{benutzername}\projects\contenido. Sollte der Pfad zum WSL-Dateisystem nicht angezeigt werden, kann man es manuell angeben.

Es gibt im Netz auch Anleitungen für weitere IDEs wie z. B. für Eclipse oder NetBeans.

Wichtigste DDV Befehle

Es gibt eine Menge an DDV Befehlen, siehe DDEV Docs - Using the ddev Command, die wichtigsten für die tägliche Arbeit sind folgende:

  • ddev start: Das DDEV Projekt starten
  • ddev launch: Das DDEV Projekt in einem Browsertab öffnen
  • ddev describe: Die Detailinformationen (Hostname, Datenbankverbindungsparameter, usw.) zum DDEV Projekt anzeigen lassen
  • ddev stop: Das DDEV Projekt stoppen