sle/phing-typo3-deployer

Phing TYPO3 Deployer is a powerful deployment tool for TYPO3 CMS

2.4.1 2021-09-03 08:57 UTC

README

Copyright 2017 by Steve Lenz

Tracis CI

Inhalt

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:

  1. 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
        }
      }
    }
  2. 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
  3. 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:

  1. 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
  2. Composer-Pakete installieren

    $ composer install
  3. 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
      
  4. 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.

  5. vHost konfigurieren

    Der vHost muss auf das Verzeichnis <project-root>/releases/current/web zeigen.

  6. 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
  7. 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