Entwicklungsumgebung einrichten

Das Einrichten der Testumgebung erfolgt in mehreren Schritten, die im folgenden beschrieben sind. Falls es dabei zu unerwarteten Fehlermeldungen kommt, bitte die letzten Schritte noch einmal genau anschauen und gegebenenfalls wiederholen. Auch ein Blick ins Fehlerhandbuch hilft meistens, da bereits viele Fallstricke entdeckt und beschrieben wurden.

1. Das Betriebssystem vorbereiten, entweder Linux oder Windows

Windows 10

Programme installieren

Unter Windows ist es standardmäßig nicht möglich, “einfach“ die Linux Distribution Ubuntu zu installieren. Dazu muss vorab erst das WSL2 aktiviert / installiert werden werden (Punkt 1). Im Anschluss ist eine Installation von Ubuntu (18.04 oder 20.04 oder höher) möglich. Zudem muss Docker installiert werden, in dem dann die Entwicklungsumgebung laufen kann (Punkt 2).

1. WSL2 unter Windows10 aktivieren und Ubuntu 20.04 installieren:
   1. Aus dem Microsoft-Store: https://aka.ms/wslstorepage (verfügbar seit Nov. 2022)
   2. Manuell unter von WSL
2. Docker für Windows installieren: Docker Desktop on Windows
3. Unter Windows muss in der Hosts-Datei (%windir%\system32\drivers\etc) folgende Eintragung gemacht werden:

127.0.0.1	docker.team-opencaching.de
127.0.0.1	try.docker.team-opencaching.de

Danach kann Ubuntu gestartet werden (z.B. im “Such“-Menü nach Ubuntu suchen und anklicken). Beim erstmaligen Starten von Ubuntu müssen ein Benutzername und ein Passwort festgelegt werden.

Im Anschluss den Punkten folgen und ausführen, die im nächsten Schritt “Linux” beschrieben werden.

Linux

Der Linuxartikel wurde erstellt auf Lubuntu 18.04, aktualisiert mit 22.04 und erweitert mit Debian 12

Programme installieren

Folgende Programme sind notwendig und müssen vorab installiert werden: PHP (aktuell mind. PHP7.4, später PHP8), diverse PHP-Erweiterungen, docker-compose, mariadb-client. Für die PHP-Erweiterungen ist eventuell ein zusätzliches PPA-Repository notwendig. Dessen Installation erfordert je nach Betriebssystem ein unterschiedliches Vorgehen.

Ubuntu:
sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php

Debian:
sudo apt install software-properties-common ca-certificates lsb-release apt-transport-https
curl -sSL https://packages.sury.org/php/README.txt | sudo bash -x

Die Pakete lassen sich mit folgenden Befehlen installieren (Versionsnummer kann abweichen).

sudo apt update
sudo apt install php8 php8.0-mbstring php8.0-curl php8.0-xml php8.0-mysql
sudo apt install docker-compose
sudo apt install mariadb-client

Sollten beim Installieren der Pakete Fehlermeldungen auftreten, ist es empfehlenswert, die Pakete einzeln zu installieren und auftretende Fehler/Abhängigkeiten einzeln zu lösen.

Nutzer in docker-Gruppe aufnehmen

Der aktuelle Benutzer muss in die Gruppe “docker” aufgenommen werden, sonst kann es passieren, dass dieser keinen Zugriff auf die Dockercontainer bekommt.

sudo usermod -aG docker $(id -un)

Die Änderung wird aber erst nach einem Ab-/Anmelden des Nutzers wirksam. Überprüft werden kann dies danach mittels

id

Hier muss die “docker”-Gruppe aufgelistet sein. Beispiel:

uid=1000(user) gid=1000(user) groups=1000(user),4(adm),24(cdrom),..,128(docker)

Eigenschaften der Docker Socket-Datei prüfen

Den folgenden Befehl ausführen, um die Eigenschaften der Datei anzeigen zu lassen:

sudo ls -la /var/run/docker.sock

Die Datei muss dabei ‘docker’ zugewiesen sein:

rw-rw---- 1 root docker 0 Dec 21 19:16 /var/run/docker.sock

Ist dies nicht der Fall, muss die Zugehörigkeit geändert werden:

chgrp docker /var/run/docker.sock

2. Sourcecode von Git laden

Github

Zwar ist zum Herunterlden des Sourcecodes keine Account auf GitHub notwendig, aber zum Hochladen wird einer benötigt. Daher sollte zuerst einen Account auf https://github.com/ angelegt werden.

optional: SSH-Keys für Repositorys anlegen und in Github eintragen

siehe https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh
oder: https://www.heise.de/tipps-tricks/SSH-Key-fuer-GitHub-Repositories-einrichten-4627459.html

Git lokal installieren

Windows:
siehe: https://github.com/git-for-windows/git/releases

Linux:

sudo apt install git

Sourcecode lokal herunterladen

Ein Terminal öffnen, folgende Kommandos ausführen und dabei Namen und Email-Adresse des Git-Accounts eintragen:

git config --global user.name "Your Name Here"
git config --global user.email "your_email@youremail.com"

Im Verzeichnis "home" einen Ordner "opencaching" (Name beliebig) anlegen. Dort folgenden Code ausführen. Dies legt einen Ordner mit dem Namen “oc-server3“ an, lädt den OC-Code aus deinem Github-Fork herunter und kopiert ihn in diesen Ordner.

git clone git@github.com:<DeinGithubBenutzername>/oc-server3

Im Anschluss in den Ordner “oc-server3“ wechseln und den folgenden Befehl ausführen, um bei einem Update den neuesten Sourcecode aus dem Opencaching.de-Repository erhalten zu können:

cd oc-server3
git remote add upstream git@github.com:OpencachingDeutschland/oc-server3

Mit folgendem Befehl gibt es eine Übersicht über die verknüpften Repositorys, die (abgesehen vom Nutzernamen ‘Slini11’) wie in der Grafik aussehen müssen:

git remote -v

Nun den Branch “development“ auschecken:

git checkout development

Und den Development-Branch auf aktuellen Stand bringen:

git pull --rebase upstream development 

Weiterführende Informationen zu Git

Diese sind unter anderem im OC-Wiki zu finden

3. Docker Entwicklungsumgebung initalisieren

Entwicklungsumgebung zum ersten Mal starten

(siehe auch: Github: the docker environment)

Zuerst in den Projektordner “oc-server3“ navigieren und dort die Installation der Testumgebung starten. Es stehen hierfür zwei Befehlsfolgen zur Verfügung:

Scripte einzeln ausführen

• Die Dockerumgebung starten (ggf. der Benutzerkontensteuerung zustimmen). Dieser Vorgang dauert ein paar Minuten.

./psh.phar docker:start

• In den Dockercontainer hinein verbinden

./psh.phar docker:ssh

• Anschließend in der sich öffnenden docker bash einmalig das Initialisierungsskript starten. Dieser Vorgang dauert ein paar Minuten.

./psh.phar docker:init

• Zuletzt den Dockercontainer wieder verlassen

exit

• Die Entwicklungsumgebung steht nun über den Browser bereit unter:

 http://docker.team-opencaching.de bzw.
 http://try.docker.team-opencaching.de

• Das Passwort für den Benutzer root lautet developer. Das Passwort der anderen Benutzer (Benutzernamen siehe Datenbank) lautet password

Das start-Script ausführen

• Statt die Schritte einzeln auszuführen, kann die Dockerinitialisierung auch mit einem einzigen Befehl gestartet werden:

./psh.phar docker:start-clean

Dieser Befehl führt alle oben beschriebenen Kommandos aus, löscht zusätzlich die Dockercontainer, den Cache des Testservers sowie alle von git ignorierten Dateien. Dieser Vorgang dauert ein paar Minuten länger und empfiehlt sich, wenn eine saubere Umgebung hergestellt werden soll oder während der Initialisierung unbehebbare Fehler auftreten.

• Die Entwicklungsumgebung steht nun über den Browser bereit unter:

 http://docker.team-opencaching.de bzw.
 http://try.docker.team-opencaching.de

• Das Passwort für den Benutzer root lautet developer. Das Passwort der anderen Benutzer (Benutzernamen siehe Datenbank) lautet password

Entwicklungsumgebung ein weiteres Mal starten

Die Testumgebung kann z.B. nach einem Neustart des Rechners im Projektordner gestartet werden mit:

./psh.phar docker:start

Entwicklungsumgebung stoppen

Die Testumgebung kann im Projektordner gestoppt werden mit:

./psh.phar docker:stop

4. Die Testdatenbank füllen

Während der Installation wird eine Testdatenbank importiert, die bereits eine kleine Menge an Caches und Nutzern beinhaltet. Ein manueller Import des Datenbankdumps ist somit (seit März 2021) nicht mehr notwendig.

Für den Fall, dass trotzdem Daten exportiert / importiert werden sollen, können folgende Abschnitte berücksichtigt werden: Login auf der Test-Datenbank im Dockercontainer

mysql -uroot -proot -hmariadb opencaching

Datenbank zurücksetzen

(noch zu verifizieren und zu verbessern..)
im Docker per mysql auf die mariadb verbinden
'DROP' opencaching DB
exit mysql und docker
Nun entweder im Docker ein ./psh.phar docker:init ausführen oder wenn das Fehler bringt, vorher den kompletten git-Pfad neu aufsetzen
Ev. funktioniert auch der Weg, den DB-Dockercontainer aufzurufen, zu löschen, etc.
(docker-volume ls)

Datenbank innerhalb des Dockercontainers exportieren

mysqldump -uroot -proot -hmariadb opencaching > file.sql

Datenbank außerhalb des Dockercontainers exportieren

mysqldump --complete-insert --user root -proot --host 0.0.0.0 opencaching > dump.sql

Datenbank im phpStorm exportieren

Auf der rechten Bildschirmseite den Databasedialog ausklappen rechte Maustaste auf die zu exportierende Datenbank “opencaching” => “Export with ‘mysqldump’”

Im Exportmenü die Zeile “Statements” umstellen auf “Insert with columns” und eventuell den Ausgabepfad “Out Path” anpassen. Im Kommandofeld den Parameter “--routines“ ergänzen und dann “Run” drücken

Datenbank-Dump im Dockercontainer importieren

Zuerst wird eine eventuell existierende Datenbank gelöscht und neu angelegt.

./psh.phar docker:init

Im zweiten Schritt wird die Datenbank mit dem Dump gefüllt.

mysql -uroot -proot -hmariadb opencaching < file.sql

Datenbank-Dump im phpStorm importieren

Auf der rechten Bildschirmseite den Databasedialog ausklappen rechte Maustaste auf die Datenbank => “Restore with ‘mysql’”

Im Importmenü den Eingabepfad “Path to dump” anpassen, dann “Run” drücken

Datenbank in phpStorm anzeigen

Ggf. kann es passieren, dass die Datenbank nicht automatisch in phpStorm angezeigt wird. Dazu muss eine neue MariaDB im Datenbank-Menü angelegt werden.

Im Anschluss sind die Daten wie im folgenden Screenshot einzutragen. User: “root“ Password: “root“

5. Die Entwicklungsumgebung vorbereiten

Gegebenenfalls sind an der Programmierumgebung Änderungen vorzunehmen, um zum Beispiel einheitlich formatierten Code zu schreiben.

Einrichtung des PHP Code Styles am Beispiel von phpStorm

Unter Settings / Code Style / PHP rechts auf “Set from…” klicken und “PSR-12” auswählen. Einstellung mit “Apply” bestätigen.

Pfade einrichten

-

hilfreiche Plugins für phpStorm

-

Synchronisieren/Wiederherstellen der Benutzereinstellungen mittels JetBrains-Server

Sofern man bei JetBrains einen Account hat, kann man mit diesem die Einstellungen der lokalen IDE synchronisieren und z.B. nach einer Neuinstallation von dort wiederherstellen.

Hierzu in der IDE rechts oben auf das Zahnrad klicken und “Settings Sync is off” auswählen.

Im folgenden Fenster den Button “Enable Settings Sync” klicken und danach alle Einstellungen auswählen, die man sichern möchte. Ein Klick auf “Push Settings to Account” sichert die Einstellungen. Ein Klick auf “Get Settings from Account” stellt sie wieder her, sofern sie vorher dorthin gesichert wurden.

6. Das Fehlerhandbuch lesen (gilt insbesondere für die Schritte #1-#4 :wink:)

.. neue Unterseite..