README

Inhalt

Einleitung
Einrichtung eines neuen Projekts
Einrichtung des Projekts auf dem Zielsystem
Einrichtung für die automatisierte Veröffentlichung
Hooks
Properties
FAQ
Migration
- Version 1.x auf 2.x

Einleitung

Was ist das Ziel dieses Pakets?

Phing Typo3 Deployer basiert auf dem Build-Tool Phing und dient zum automatisierten Veröffentlichen, i.S.v. Continuous Intregration und Continuous Depoyment, von TYPO3 CMS Instanzen.

Voraussetzungen

PHP 7
TYPO3 CMS 7 || 8 im Composer-Mode
Kommandozeile
Unix or Linux
Ausführung mit den nötigen Berechtigungen des Web-Users (i.d.R. www-data)

Projektstruktur

Dieses Tool benötigt und generiert folgende Verzeichnisstruktur und Dateien:

bin/
releases/
    current/
    previous/
    next/
rsync/ -> Wird nur generiert, wenn 'install-rsync-excludes' aktiviert ist.
    excludes.txt
shared/
typo3/
    composer.json
vendor/
build.custom.properties
build.env.properties
build.hook.xml
build.xml
composer.json
composer.lock

Einrichtung eines neuen Projekts

Für die Einrichtung sind lediglich diese drei Schritte notwendig:

composer.json im Webroot (htdocs-Verzeichnis) des Projekts erstellen

{
  "name": "my/typo3-project",
  "license": "MIT",
  "description": "",
  "type": "project",
  "require": {
    "sle/phing-typo3-deployer": "[VERSION]"
  },
  "config": {
    "vendor-dir": "vendor",
    "bin-dir": "bin"
  },
  "minimum-stability": "stable",
  "scripts": {
    "post-install-cmd": [
      "Sle\\PhingTypo3Deployer\\Composer\\Scripts::postInstall"
    ],
    "post-update-cmd": [
      "Sle\\PhingTypo3Deployer\\Composer\\Scripts::postUpdate"
    ]
  },
  "extra": {
    "sle/phing-typo3-deployer": {
      "install-rsync-excludes": false
    }
  }
}

Composer-Pakete installieren

$ composer install

Bei der Installation wird folgende Projektstruktur generiert:

bin/
vendor/
typo3/
    composer.json
build.custom.properties
build.env.properties
build.hook.xml
build.xml
composer.json
composer.lock

Dateien zur Versionskontrolle hinzufügen

Folgende Dateien müssen zur Versionskontrolle hinzugefügt werden:

rsync/
    excludes.txt
typo3/
    composer.json
build.custom.properties
build.hook.xml
composer.json
composer.lock

Hinzufügen mit git:

$ git add -A && git commit -m '[Build] Add phing-typo3-deployer'

Einrichtung des Projekts auf dem Zielsystem

Unter dem Begriff Zielsystem wird hier ein Webserver oder Ähnliches verstanden.

Für die korrekte Einrichtung auf dem Zielsystem sind folgende Schritte erforderlich:

Projektdatein auf das Zielsystem kopieren

Die Projektdateien bzw. Verzeichnisse, die sich in der Versionskontrolle befinden, müssen auf das Zielsystem kopiert werden. Die Verzeichnisstruktur sieht nun wie folgt aus:
```
typo3/
    .env.dist
    composer.json
    composer.lock
build.custom.properties
build.hook.xml
composer.json
composer.lock
```
Composer-Pakete installieren
```
$ composer install
```
Bei einigen vServern (bspw. Mittwald vServer) kann Phing den absoluten Pfad nicht korrekt auslesen. Zudem wird PHP in der Kommandozeile mit php_cli statt mit php aufgerufen. Daher können die Umgebungsvariablen, in der nun angelegten build.env.properties, umkonfiguriert werden.
- Bsp. Mittwald vServer ENV-Konfiguration:
```
# Base directory configuration
base.dir = /home/www/p<XXXXXX>/html/<project-dir>

# Commandline configuration
cmd.php = php_cli
cmd.composer = composer
```
Initiales Release veröffentlichen

Das Verzeichnis mit der akteullen Version befindet sich unter releases/current/. damit dieses erstellt werden kann, muss folgender Befehl ausgeführt werden:
```
$ bin/phing ci:release
```
Siehe auch Wie erstellt man ein neues Release?
Achtung!

Ggf. kann es bei der Ausführung auf Mittwald vServer dazu kommen, das Phing nicht die build.xml finden kann. Hierfür sollte alternativ eine phing.phar installiert werden (siehe https://www.phing.info/). Die phing.phar sollte idealerweise in das Root-Verzeichnis des Projekt-Reporitories aufgenommen und auch mit deployed werden.
```
$ php_cli phing.phar ci:release
```
Dabei werden folgende Datein und Verzeichnisse erstellt:
```
releases/
    current/
        bin/
        vendor/
        web/
    previous/ -> Wird ab dem zweiten Release generiert und beinhaltet immer das vorherige Release.
        bin/
        vendor/
        web/
build.env.properties
```
In das Verzeichnis releases/current/ werden die Daten aus dem Verzeichnis typo3 kopiert und composer install ausgeführt.
vHost konfigurieren

Der vHost muss auf das Verzeichnis <project-root>/releases/current/web zeigen.
TYPO3 CMS auf dem Zielsystem installieren

Nun muss das TYPO3 CMS auf dem Zielsystem initial installiert werden. Dies kann über den TYPO3 Install Wizard oder die typo3console erfolgen.

Installation mit Hilfe der typo3console:
```
releases/current$ bin/typo3cms install:setup
```
Zentrale Ablage der gemeinsamen Dateien

Die gemeinsamen Dateien (shared data) müssen nun noch zentral abgelegt werden, damit sie für zukünftige Releases verfügbar sind:
```
$ bin/phing init:shared
```
Hierbei werden die LocalConfiguration.php sowie die Verzeichnisse fileadmin und uploads in das Verzeichnis shared kopiert, da diese immer gleich bleiben und somit für zukünftigen Releases zentral zur Verfügung stehen. Zudem werden die originale durch Symlinks ersetzt.

Generierte Verzeichnisstruktur für shared:
```
releases/
    current/
shared/
    .env (Wenn typo3/.env.dist vorhanden ist)
    fileadmin/
    uploads/
    typo3conf/
        LocalConfiguration.php
```

Einrichtung für die automatisierte Veröffentlichung

Die automatierte Aktualisierung des Projekts kann über Git und Jenkins erfolgen. Bei der Synchronisation müssen folgende Dateien aktualisiert werden:

typo3/
build.custom.properties
build.hook.xml
composer.json
composer.lock

Hooks

Alle Verfügbaren Hooks befinden sich in der Datei build.hook.xml.

Properties

Globale Properties

Eine Liste der verwendbaren Properties befindet sich in der Datei src/phing/config/build.properties.

Eigene Properties

Eigene Properties können in der Datei build.custom.properties hinterlegt werden und stehen in den Hooks zur Verfügung.

Environment Properties

In der Datei build.env.properties können Environment-Konfigurationen vorgenommen werden.

FAQ

Auflistung aller verfügbaren Kommandos

$ bin/phing

Lokale Entwicklung

Die lokale Entwicklung findet im Verzeichnis htdocs/typo3 statt. Die komplette Verzeichnisstruktur nach der installation sieht wie folgt aus:

bin/
typo3/
    vendor/
    web/
    composer.json
    composer.lock
vendor/
build.custom.properties
build.env.properties
build.hook.xml
build.xml
composer.json
composer.lock

Der vHost sollte auf typo3/web zeigen.

Wie erstellt man ein neues Release?

$ bin/phing ci:release

Alternativ kann man das Release über 3 dedizierte Targets erstellen und veröffentlichen lassen. Zwischen den Targets können eigene Server-Skripte, bspw. Anpassung von Berechtigungen, ausgeführt werden. (Diese drei Targets werden in der Reihenfolge auch vom ci:release ausgeführt)

$ bin/phing ci:release:create:next
$ bin/phing ci:release:publish:next
$ bin/phing ci:release:post-actions

Jenkins Projekt Konfiguration

Folgende Dateien müssen synchronisiert werden

typo3/
build.custom.properties
build.hook.xml
composer.json
composer.lock

Neues Release mit Hilfe der Remote-Shell erstellen

$ ssh <user>@<server>
<server>$ cd <webroot>/<project>
<server>/<webroot>/<project>$ composer install
<server>/<webroot>/<project>$ bin/phing ci:release

Siehe auch Wie erstellt man ein neues Release?

RSYNC

Installation der excludes.txt

Über folgende Composer-Konfiguration kann die excludes.txt automatisch installiert werden:

"extra": {
    "sle/phing-typo3-deployer": {
        "install-rsync-excludes": true
    }
}

Konfiguration

rsync --delete -aze ssh --iconv=UTF-8 --exclude-from $WORKSPACE/rsync/excludes.txt $WORKSPACE/ <user>@<server>:/<webroot>/<project>/

In der Datei rsync/excludes.txt können die RSYNC-Excludes konfiguriert werden:

rsync
releases
shared
build.env.properties
build.xml

Versionskontrolle

Folgende Dateien und Verzeichnisse sollten nicht in die Versionskontrolle aufgenommen werden:

build.env.properties
build.xml
bin
shared
vendor
releases

Migration

Version 1.x auf 2.x

Ab der Version 2 muss der Pfad des TYPO3 Web-Verzeichnises über die build.custom.properties wie folgt konfiguriert werden:

# TYPO3 CMS web-dir
#
# This should be the same value as in composer.json 'web-dir'
#
# Example:
# ========
# "extra": {
#   "typo3/cms": {
#       "cms-package-dir": "{$vendor-dir}/typo3/cms",
#       "web-dir": "web"
#   },
# }
typo3-cms.web-dir = web

sle / phing-typo3-deployer

Maintainers

Details