typo3.org Entwicklerbox - Up and running 

typo3.org soll relauncht werden. Mit dieser Anleitung kannst du dir eine Entwicklungsbox für das Projekt herunterladen, lokal einrichten und damit bei der Entwicklung der neuen Seite helfen.

$x != $u;

Christiane Helmchen
ist stets darauf bedacht, dass unsere Software anständig getestet und stabil gestaltet wird.
Lesedauer: ca. 4 Minuten

Note: If you are looking for an English instruction, please follow this link which will show you a README file containing similar information to this article: https://gitlab.pluspunkthosting.de/T3O/typo3.org

Voraussetzungen, um mit der Entwicklung beginnen zu können

Um an der Seite (typo3.org) mitwirken zu können, benötigst du natürlich zuerst einen Zugriff auf die Code-Basis. Diesen erhältst du, indem du Thomas Löffler kontaktierst, bevorzugt per Slack. Wenn du noch keinen Slack Account hast, kannst du dich hier registrieren: https://forger.typo3.org/slack und Thomas dann direkt anschreiben. Nachdem du freigeschaltet wurdest, kannst du dich um eine lokale Entwicklungsumgebung kümmern.

Um dich an der Entwicklung der typo3.org zu beteiligen, haben wir unter https://gitlab.pluspunkthosting.de/T3O/typo3.org ein passendes Vagrant-Projekt zur Verfügung gestellt. Allerdings benötigst du für die fehlerfreie Nutzung Vagrant (https://www.vagrantup.com/downloads.html ) und VirtualBox (https://www.virtualbox.org/wiki/Downloads ). Vagrant erspart dir die Mühe, einen lokalen Webserver zu konfigurieren. Sowohl Vagrant als auch VirtualBox können auf den angegebenen Seiten heruntergeladen und installiert werden. 

Falls du bei der Installation auf Probleme stoßt, kann dies mit den Versionen der verwendeten Software zusammenhängen. Unsere Vagrant-Box ist mit den folgenden Versionen erprobt:

  • VirtualBox 4.3.40 und 4.3.30
  • Vagrant 1.8.5 und 1.6.3

Sollte es für dich nicht möglich sein, diese Versionen zu verwenden, z.B. weil du bereits eine andere Vagrant-Version benutzt, dann kannst du uns gerne über technik@punkt.de kontaktieren und wir schauen, ob wir eine Lösung dafür finden.

Aufsetzen der Entwicklungsumgebung

Klon dir hierzu unser Git-Projekt von https://gitlab.pluspunkthosting.de/T3O/typo3.org und begib dich in den angelegten Ordner:

git clone https://gitlab.pluspunkthosting.de/T3O/typo3.org.git
cd typo3.org/

Um die VagrantBox zu starten, musst du nun lediglich folgenden Befehl aufrufen:

vagrant up

Damit wird die Box heruntergeladen und gestartet sowie das git-Projekt typo3.org noch einmal in die Box geklont. Dies kann einige Minuten dauern.

Verbinde dich danach als Nutzer vagrant per SSH auf die Box, wechsle in den Ordner des geklonten Projekts und führe das Initialisierungsskript einmal aus:

vagrant ssh
cd /var/www/t3o
./t3o.sh init

Jetzt werden per composer alle Abhängigkeiten des Projekts installiert und die Datenbankinhalte gezogen. Dabei müssen einige Nutzereingaben getätigt werden:

  • Authentication required (git-t3o.typo3.org): Username & Passwort
    (Gemeint ist hier der Login, den ihr für die Freigabe bei Thomas Löffler angegeben habt.)
  • Do you want to store credentials for git-t3o.typo3.org in /home/proserver/.composer/auth.json ? [y/n]
    (Wir empfehlen aus Sicherheitsgründen "n".)

Danach kannst du dir das Ergebnis direkt unter https://local.typo3.org/ ansehen.


Achtung: Der Browser zeigt einen Zertifikatsfehler an – die Seite muss als Ausnahme genehmigt werden. Nun sollte die neue Startseite von typo3.org sichtbar sein.

Wie kannst du Änderungen vornehmen? 

Synchronisation mit PhpStorm

Um nun tatsächlich Änderungen am Projekt durchzuführen und ins zentrale git-Repository zu übertragen, müssen diese zuerst lokal vorgenommen werden. Im Folgenden wird am Beispiel von PhpStorm erklärt, wie du bequem mit einer IDE und der Box arbeiten kannst.

Bisher liegt der Code des Projekts einerseits in der heruntergeladenen Vagrant-Box und andererseits irgendwo lokal auf deinem Rechner – dort, wo du git clone ausgeführt hast. Wir arbeiten bevorzugt an der lokal vorhandenen Kopie, der Browser greift aber auf den Code in der Box zu. Deshalb benötigen wir einen Weg, um die lokalen Dateien möglichst einfach und automatisiert mit den Box-Dateien zu synchronisieren. Dafür verwenden wir die Deployment-Option von PhpStorm, so dass Änderungen, die lokal im PhpStorm durchgeführt werden, automatisch in die Box hochgeladen werden.

Um das Deployment einmalig einzurichten, sind die folgenden Schritte notwendig:

1. Öffne den Hauptordner des Geklonten Projekts im PhpStorm (Also typo3.org)

  • Unter "Preferences" oder "Settings": Suche die Option "Deployment"
  • Füge eine neue Deployment-Konfiguration hinzu (Klick auf +) – der Name ist beliebig
Screenshot der Anmeldung in der typo3.org Entwicklerbox: Deployment Konfiguration

2. Stelle die Konfiguration wie im folgenden Screenshot ein.

Falls du den Pfad zu deinem Private Key nicht kennst, führe "vagrant ssh-config | grep IdentityFile | awk '{print $2}'" in der Konsole deiner Wahl aus und kopiere das ausgegebene Ergebnis in das entsprechende Feld.

Screenshot des Settings der typo3.org Entwicklerbox: Deployment Konfiguration

Und teste die SFTP-Verbindung (Button "Test SFTP connection") und akzeptiere im Popup die Verbindung mit "Yes".

Screenshot der Aufforderung, die SFTP-Verbindung zu testen

3. Wechsle auf den Tab "Mappings" und passe den Deployment-Pfad entsprechend des Screenshots an

typo3.org Entwicklerbox: Deployment Pfad anpassen

4. Passe die Optionen für die Synchronisation an (Deployment > Options). 

Der Screenshot zeigt eine mögliche Einstellung. Besonders wichtig ist der Haken bei "Upload external changes"– dies führt dazu, dass Änderungen durch grunt ebenfalls erkannt werden, wenn es in der IDE ausgeführt wird.

Screenshot der typo3.org Entwicklerbox: Synchronisation im Deployment anpassen

5. Kopiere die durch composer hinzugefügten Dateien von der Box einmalig auf deinen lokalen Rechner

Bestätige anschließend, dass du lokale Dateien überschreiben möchtest (Download from t3o). Du solltest außer der LocalConfiguration.php und der PackageStates.php bisher lokal keine Dateien in diesem Ordner haben.

 (!) Warnungen für Dateien in ..../node-modules/..../.bin können getrost ignoriert werden. 

typo3.org Entwicklerbox: Anleitung zum Kopieren der Daten

Der composer-Workflow

Das Projekt verwendet composer zur Installation von Extensions, insbesondere auch für die Extension t3olayout. Für den Build-Prozess von CSS und JavaScript wird grunt verwendet. Wir empfehlen sowohl composer als auch grunt in der Box auszuführen, damit keine versionsbedingten Fehler auftreten. Wie man Änderungen in t3olayout vornimmt zeigt der folgende Workflow:

1. Starte grunt watch in deiner IDE oder der Konsole in der Box (Zugang per SSH)

Konsole in der Box:

cd /var/www/t3o/html/typo3conf/ext/t3olayout/Resources/Private 
./node_modules/grunt-cli/bin/grunt watch

2. Ändere eine Datei

z.B. typo3.org/html/typo3conf/ext/t3olayout/Resources/Private/SASS/ Base/_colors.scss und speichere. Nun sollte grunt die Änderungen erkennen und die Datei main.css neu bauen. Im Browser sollten die Änderungen nach Neuladen der Seite ebenfalls sichtbar werden. 

SSH-Zugang als Nutzer "proserver"

Gehe in den Hauptordner des Projekts:

cd irgendein/Pfad/typo3.org/

Finde den Pfad zum private key:

vagrant ssh-config | grep IdentityFile | awk '{print $2}'

Falls der Aufruf so nicht klappt:

vagrant ssh-config

( nimm in dieser Ausgabe den Pfad hinter "IdentityFile") 

Zugang auf die Box per SSH:

ssh -A -i /path/to/private_key proserver@local.typo3.org

3. Übertrage deine Änderungen in der Extension ins zentrale git-Repository:

In der Box:

cd /var/www/t3o/html/typo3conf/ext/t3olayout
git commit
git push

Lokal:
Passe die Deployment-Optionen im PhpStorm an, damit auch .git synchronisiert wird und arbeite im gleichen Ordner wie auf der Box.

4. Führe in der Box im Hauptordner des Projekts Folgendes aus: "composer update t3o/t3olayout". Damit wird der neueste Stand des Repositorys der Extension im Hauptprojekt gezogen und der entsprechende git commit in der Datei composer.lock auf der Box gespeichert.

5. Kopiere die Datei composer.lock von der Box ins lokale Projekt: Option "Download from t3o" (siehe Screenshot bei Punkt 5 im oberen Teil).

6. Übertrage die Datei composer.lock Hauptprojekt mit git commit und git push ins zentrale Repository auf gitlab.

Herzlichen Glückwunsch, nun kannst du dich aktiv an der Entwicklung von typo3.org beteiligen.

P.S. Nachdem du Änderungen in den Master gepushed hast, können diese nur von Thomas Löffler und Joachim Mathes abgenommen und auf den Server übertragen werden.

Wissenswertes zur Box

  • Man kann die Box jederzeit wegwerfen und sie neu aufsetzen, z.B. wenn man die Datenbank unwiederbringlich zerstört hat.
    • im Hauptordner des Projekts "vagrant destroy" aufrufen
    • "Are you sure you want to destroy the 'default' VM? [y/n]" mit "y" beantworten
  • Sollte aus irgendwelchen Gründen das Löschen so nicht funktionieren, kann man ebenso die VirtualBox-Software öffnen und dort die Box t3o löschen
    • "Rechtsklick auf Namen t3o > Entfernen" bzw.
    • "Rechtsklick auf Namen t3o > Schließen > Ausschalten" und dann "Rechtsklick auf Namen t3o > Entfernen"
  • Weitere hilfreiche Dokumentation (zum Beispiel zum Updaten der Box) findest du hier:
    https://gitlab.pluspunkthosting.de/T3O/typo3.org/blob/master/documentation/workflow.md


Viel Spaß beim Ausprobieren!

Teilen:

Weitere Beiträge

It’s not a bug – it’s a feature!
Annika Walter, Entwicklung bei punkt.de
Arbeiten bei punkt.de