vcdeploy - Deployment Skript

Was ist vcdeploy?

vcdeploy ist ein in PHP geschriebenes Skript, welches für die Steuerung von PHP Projekten verwendet wird. Als Backend wird ein SCM System wie Git, Bazzar oder Subversion verwendet.

Wieso vcdeploy?

Ich habe mich dazu entschlossen dieses Skript öffentlich, inklusive Quellcode anzubieten, da ich mir davon verspreche dadurch dem Skript mehr Stabilität und Sicherheit zugeben.

Wie läuft sowas normalerweise in einem Projekt? Es werden sich Gedanken gemacht, wie und mit was man das Deployment umsetzt. Anit, Phing, Capistrano u.s.w. kommen ins Gespräch. Bevor man sich dann an die “eigentliche” Lösung macht, fängt man letztendlich mit einem Bash-Script an (böse Gerüchte sind sogar verbreitet, dass manche Projekte noch händisch deployt werden). Und irgendwie bleibt man dann auch beim Bash Script, weil keine Zeit, kein weiteres Budget existieren oder was auch immer fehlt.

Das Bash Skript wächst und wird irgendwann auch sehr unübersichtlich. Tests für dieses Skript gibt es natürlich meist auch nicht. Und hier setzt vcdeploy ein. Um sich den Durchlauf der Bash-Entwicklung zu ersparen, wird hier PHP für das Deploy eingesetzt. Da es für PHP Projekte gedacht ist, sollte ja auch PHP auf den entsprechenden Rechnern vorhanden sein. vcdeploy ist bewusst einfach gehalten, um den Einstieg leicht zu machen. Da das Projekt in PHP entwickelt wurde, können die Entwickler auch ohne große Einarbeitung ein Plugin für vcdeploy schreiben.

Und das beste daran ist, man muss nicht von ganz vorne anfangen, wie es beim Deployment oft der Fall ist (was meine Erfahrung mir gezeigt hat).

Funktionsumfang

• Unterstützung von CVS, SVN und GIT Repositories
• Verwaltung der Systemkonfiguration über SCM
• Zurücksetzen der Datenbank
• Einrichtung einer neuen Systemumgebung (automatisiert)
• Protokollierung
• Benachrichtigung per Email (z.B. bei Fehlverhalten während des Deploys)
• Einfache Erweiterung durch eigene Plugins

Vorteile durch den Einsatz

• Formaler Prozess des Deployment wird klar definiert
• Automatisiertes Deployment
• Getestetes Skript - vcdeploy wird bereits eingesetzt und hat sich schon in der Praxis bewährt. Wohingegen ein neues Skript, was speziell für ein Projekt angefertigt wird, erst eine gewisse Stabilität erlangen muss.

Vorhandene Plugins

Sämtliche Funktionalität wird über Plugins verfügbar gemacht. Plugins können beliebig ergänzt und kombiniert werden. Im folgenden werden die einzelnen Plugins von vcdeploy vorgestellt, die jeweils als Kommando über vcdeploy verwendet werden können. Jedes Kommando hat eigene Parameter, die verwendet werden können. Um eine Liste der Verfügbaren Parameter zu erhalten, verwendet man vcdeploy COMMAND -h

backup-clear

Hiermit werden alle bestehenden Backups nach Spezifkation gelöscht. In der Konfigurationsdatei wird mit der Variablen $conf[‘backup_max_days’] festgelegt, wie lange ein Backup Satz aufbewahrt wird (Standard ist 7 Tage).

backup-db

Optionen:

  -p project, --project=project     Create backup of this project
                                    database(s)
  -d database, --database=database  Only create backup of this database
  -A, --all-databases               Create backup of all existing databases
  -h, --help                        show this help message and exit

Wird der Parameter -A übergeben, werden von allen bestehenden Datenbanken auf dem Server Backups erstellt. Hierbei wird für jede Datenbank eine eigene Datei erzeugt. Mit dem Parameter -p werden Datenbanken zu einem bestimmten Projekt erzeugt. Mit dem Parameter -d wird von einer spezifischen Datenbank ein Backup erstellt. Wir kein Parameter übergeben, werden von allen Datenbanken, welche Projekte zugeordnet sind, ein Backup erstellt.

Alle Backups werden in dem Verzeichnis abgelegt, welches mit

$conf['backup_dir']

in der Konfigurationdatei hinterlegt wurde (Standard /srv/backups).

backup-files

Es werden Backups zu den in der Konfigurationsdatei hinterlegten Verzeichnissen/Projekten angelegt.

backup-ls

Listet die vorhanden Backup-Sätze auf.

backup-rsync

Führt ein Backup über Rsync aus.

command-ls

Listet alle benutzerdefinierten Kommandos auf, die in der Konfigurationsdatei hinterlegt wurden.

command

Für einen benutzerdefinierten Befehl aus.

init-system

Wenn eine neue Linux Umgebung eingerichtet wird, kann man mit diesem Plugin automatisch Verzeichnisse anlegen und eine Liste von Paketen (deb, rpm) installieren. Besonders wenn Virtualisierung eingesetzt wird, ist dies eine sehr hilfreiche Funktion.

permission

Mit dem Befehl permission werden Dateiberechtigungen und Besitzer gesetzt. Dieser Befehl sollte nur für Dateien und Verzeichnisse verwendet werden, die keinen Projekt angehören (da für Projekte stattdessen rollout verwendet werden sollte).

Die Berechtigungen werden über den Array

$conf['permissions']

festgelegt, indem folgende Schlüssel verwendet werden:

• name = Dateiname oder Verzeichnisname (absoluter Pfad!)
• rec = yes (falls rekursiv), files (rekursiv, aber nur auf Dateien anwenden) dirs (rekursiv, aber nur auf Verzeichnisse anwenden) oder no (nicht rekursiv, standard)
• mod = die zu setzende Berechtigung (z.B. 664)
• own = der zu setzende Besitzer

name ist mit mod/own erforderlich.

Beispiel:

$conf['permissions'][0]['name'] = '/www/htdocs';
$conf['permissions'][0]['rec'] = 'files';
$conf['permissions'][0]['mod'] = 664;
$conf['permissions'][0]['own'] = 'www-data:www-data';
$conf['permissions'][1]['name'] = '/www/htdocs/sites/default';
$conf['permissions'][1]['mod'] = '550';

Dadurch wird im Verzeichnis /www/htdocs rekursiv allen Dateien (nicht Verzeichnissen) die Berechtigung 664 (Besitzer darf schreiben und lesen, Gruppe darf schreiben und lesen) zugewiesen und der Besitzer www-data mit der Gruppe www-data zugewiesen. Dem Verzeichnis /www/htdocs/sites/default wird die Berechtigung 550 zugewiesen (nicht rekurzsiv).

release-create

release-ls

Listetet alle vorhanden Releases auf.

reset-db

Ersetzen einer lokalen Datenbank durch einen SQL Dump, der auch von einem externen Rechner automatisch generiert werden kann (mit Hilfe einer SSH Verbindung).

reset-dir

Synchronisiert Dateien und Verzeichnisse mit einem externen System oder einen Datendump. reset-dir setzt als letzten Arbeitsschritt noch die Dateiberechtigungen, falls diese zum Projekt hinterlegt sind. Wird der Parameter -P verwendet, wird dieser Arbeitsschritt ausgelassen.

rollout-all

Führt ein rollout und ein rollout-system hintereinander aus.

rollout-system

Die Konfigurationsdateien werden über ein SCM (wie GIT oder SVN) gepflegt. Mit rollout-system wird diese Konfiguration auf dem System aktiviert. Es können dazu auch bestimmte Dienste gelistet werden, die nach dem Deploy einen Restart benötigen, welche dann automatisch durchgeführt werden.

Über $conf[‘system_source’] wird festgelegt, welches Verzeichnis als Quelle für den Rollout-Vorgang verwendet wird. Mit $conf[‘source_scm’] wird festgelegt, welches SCM zum Einsatz kommt (git, svn, bzr, cvs oder static). Wird static verwendet, wird keine Aktualisierung des Quellverzeichnisses voransgestellt, sondern die vorhandenen Dateien nur auf das Zielsystem ausgerollt. Dabei werden die Dateien aus dem Quellverzeichnis nach / kopiert. Es muss also die Verzeichnis-Hierarchie im Quellverzeichnis erstellt werden, wie sie auf dem Zielsystem zum Einsatz kommen.

rollout

Führt ein Rollout durch. Wird kein weiterer Parameter angegeben, werden alle aktiven Projekte ausgerollt. Alle vorhandenen Parameter für rollout sind:

vcdeploy rollout -h
rollout a new release

Usage:
  /Users/alex/www/system/vcdeploy/vcdeploy [options] rollout [options]

Options:
  -p project, --project=project  Rollout this project only (if skipped, all
                                 projects will be rolled out)
  -t tag, --tag=tag              Use this tag for rollout. If no tag is set
                                 with this option, default is used
                                 [rollout][tag]
  -d, --with_db                  Rollout database with this release
                                 (overwrites [rollout][with_db]
  -D, --without_db               Do not create database dump file with this
                                 release (overwrites [rollout][with_db]
  -f, --with_data                Create data dump with this release
                                 (overwrites [rollout][with_data]
  -F, --without_data             Do not create data dump with this release
                                 (overwrites [rollout][with_data]
  -b, --with_backup              Create a backup before the rollout
                                 (default with setting
                                 without_backup=FALSE)
  -B, --without_backup           Do not create a backup before the rollout
                                 (default with setting without_backup=TRUE)
  -P, --without_permission       Do not apply specified permissions
  -h, --help                     show this help message and exit

Mit “rollout” kann von Tarballs oder direkt aus dem SCM ausgerollt werden. Jeder Rollout kann durch pre_commands oder post_commands erweitert werden: die pre_commands werden vor dem eigentlich Rollout ausgeführt (z.B. um einen Serverdienst neu zu starten), die post_commands werden nach dem Rollout ausgeführt.

Die einzelnen Aktionen, die beim Rollout in dieser Reihenfolge ausgeführt werden:

1) Ausführung aller pre_commands Es werden alle Befehle auf Shell Ebene ausgeführt, die sich im Array $project[‘mein-projekt’][‘rollout’][‘pre_commands’] befinden. Die Reihenfolge der Ausführung richtet sich nach der Position des Befehls im Array.

2) Ausrollen des Codes aus SCM oder Tarball

3) Datenbank Rollout Sofern die Einstellung $project[‘mein-projekt’][‘rollout’][‘with_db’] gesetzt wurde oder diese über die Kommandozeile überschrieben wurde, werden alle Datenbanken ausgerollt, die mit $project[‘mein-projekt’][‘db’] festgelegt werden. db kann der Name einer Datenbank sein oder ein Array mit Namen. Für die Zugriffe auf den Datenbankserver werden die Berechtigungen des aktuellen Shell Benutzer verwendet. Der Shell Benutzer benötigt somit Zugiffe auf alle Datenbanken, die mit dem rollout verwendet werden. Sofern der Benutzername zum Datenbankserver von dem des Shell Benutzers abweicht, kann mit einer .my.cnf Konfigurationsdatei gearbeitet werden (auch um Hostnamen und Kennwort festzulegen).

4) Dateien Rollout Sofern die Einstellung $project[‘mein-projekt’][‘rollout’][‘with_data’] gesetzt wurde oder diese über die Kommandozeile überschrieben wurde, werden alle Verzeichnisse/Dateien ausgerollt, die mit $project[‘mein-projekt’][‘data_dir’] festgelegt werden. data_dir kann auf einen Verzeichnis oder einer Datei verweisen - oder auf einem Array mit Verzeichnissen/Dateien.

5) Dateiberechtigungen setzen Sofern zum Projekt ein Permissions Array zugeordnet wurde, wird dieser hier verwendet: $project[‘mein-projekt’][‘permissions’]

6) Ausführung aller post_commands Es werden alle Befehle auf Shell Ebene ausgeführt, die sich im Array $project[‘mein-projekt’][‘rollout’][‘post_commands’] befinden..Die Reihenfolge der Ausführung richtet sich nach der Position des Befehls im Array.

rollout setzt als letzten Arbeitsschritt noch die Dateiberechtigungen, falls diese zum Projekt hinterlegt sind. Wird der Parameter -P verwendet, wird dieser Arbeitsschritt ausgelassen.

Einsatz für Aktualisierung vieler Repositories mit einem Befehl

Um nur eine Aktualisierung des Codes aus mehreren Repositories durchzuführen, muss zu jedem Projekt der Projektpfad hinterlegt sein. Ein Beispiel zur Konfiguration sieht wie folgt aus:

// vcdeploy configuration

// overwrite git path to git binary
$conf['git_bin']       = '/opt/local/bin/git';

// log file for vcdeploy
$conf['log_file'] = '/Users/alex/vcdeploy.log';

// project configurations
$project['_common_']['scm']['type'] = 'git';

# Repository deployments
$project['xhprof']['path'] = '/Users/alex/www/system/lib/xhprof';
$project['gitosis']['path'] = '/Users/alex/www/gitosis-admin';
$project['redmine']['path'] = '/Users/alex/www/redmine';
$project['redmine']['scm']['type'] = 'svn';
$project['textmate-drupal']['path'] = '/Users/alex/Library/Application Support/TextMate/Bundles/php-drupal.tmbundle';

Es werden in dem Beispiel 5 Repositories aktualisiert. Dies bedeutet, da 4 Repositories Git als SCM verwenden, wird in jedem Verzeichnis ein git pull ausgeführt. Der Schlüsselname im Projekt-Array dient nur zur Identifikation des Projektes und muss sich somit bei jedem Projekt unterscheiden. Das Projekt redmine verwendet SVN als SCM, dafür muss der SCM Typ überschrieben werden.

Dies ist der einfachste Anwendungsfall für den “rollout” Befehl.

setup-drupal

Installiert mit Hilfe von drush als Backend eine Drupal Instanz. Hierzu können sogenannte pre_commands vor der Installation durch Drush und post_commands nach der Installation ausgeführt werden. setup-drupal setzt als letzten Arbeitsschritt noch die Dateiberechtigungen, falls diese zum Projekt hinterlegt sind. Wird der Parameter -P verwendet, wird dieser Arbeitsschritt ausgelassen.

Hier eine Übersicht der Parameter dazu:

Options:
  -P, --without_permission  Do not apply specified permissions
  -h, --help                show this help message and exit

Arguments:
  project  Name of project to setup
  command  Name of subcommand
           - reset-files: clear private and public download directories
           - reset-settings: copy drupal settings.php to target directory
           - reset-db: drop and create database to cleanup
           - install: install drupal
           - reset: run 'reset-settings', 'reset-files' and 'reset-db'
           - reinstall: run 'reset-settings', 'reset-files' and 'install'

status

Zeigt Informationen zu vcdeploy und dem System an.

system-log

Voraussetzungen

• PHP CLI muss auf allen Rechner vorhanden sein, auf dem das Skript ausgeführt werden soll
• Ein SCM (GIT, SVN oder CVS)
• Grund-Erfahrung mit der Konsole

Installation

Der Source-Code kann von GitHub bezogen werden:

git clone git://github.com/alexandermeindl/vcdeploy.git

Nun noch die Konfigurationsdatei einrichten. Es gibt mehrere Möglichkeiten, wo diese Datei abgelegt wird:

• im selben Verzeichnis wie das vcdeploy Skript, die Konfigurationsdatei muss dann config.inc.php heißen.
• im Verzeichnis /etc mit dem Namen vcdeploy.inc.php - also /etc/vcdeploy.inc.php
• im Home-Verzeichnis des Benutzers, der vcdeploy ausführt mit dem Namen .vcdeploy.inc.php - also ~/.vcdeploy.inc.php

Die Priorität der verwendeten Dateien entspricht dieser Auflisten. Als Ausgangskonfigurationsdatei kann eine Kopie der Datei config.inc.php.dist verwenden, indem man diese kopiert:

cp config.inc.php.dist config.inc.php

Nun kann man sich an die Arbeit machen und die Konfiguration festlegen. Globale Einstellungen kann man in der Datei lib/config_default.inc.php einsehen, wobei man diese Datei nicht verändern sollte, sondern stattdessen die gewünschten Einstellungen in der config.inc.php überschreibt.

Um das Skript auch außerhalb des Skriptverzeichnisses aufrufen zu können, empfielt es sich das Skriptverzeichnis im PATH mit aufzunehmen. Das kann durch folgende Anweisung erledigt werden:

echo 'export PATH="/pfad/zum/vcdeploy/verzeichnis:$PATH"' >>~/.bashrc
source ~./bashrc

Eigenes Plugin schreiben

<?php

/**
 * @file
 *
 * Beispiel eines neuen Plugins
 *
 */

$plugin['info']       = 'Meine Plugin-Beschreibung';
$plugin['root_only']  = TRUE; // für dieses Plugin sind root-Rechte erforderlich

class vcdeploy_plugin_sample extends vcdeploy {

  /*
   * Die Methode run wird automatisch ausgefuehrt, wenn das Plugin verwendet wird
   */
  public function run() {

   // Hier beliebigen PHP Code schreiben

   // Einen Test ausgeben
   $this->msg('Das gibt mein Beispiel Plugin aus.');

   // Einen Systembefehl ausführen
   $this->system('tar -cfz /root/tmp.tar.gz /tmp');
  }
}

Die Klasse dieses Plugins heißt vcdeploy_plugin_sample. sl_deploy_plugin_ muss immer als Präfix verwendet werden und dies erweitert mit dem Namen des Plugins. Hier im Beispiel wird “sample” verwendet, was wiederum bedeutet, dass die Datei unter plugins/plugin_sample.class.php abgespeichert werden muss. Ruft man nun vcdeploy -h auf, wird das neue “sample” Plugin auch in der Hilfe aufgelistet:

vcdeploy - version controlled deployment script powered by
https://alphanodes.com

Usage:
  /www/system/vcdeploy/vcdeploy [options]
  /www/system/vcdeploy/vcdeploy [options] <command> [options] [args]

Options:
  -v, --verbose      turn on verbose output
  -d, --debug        turn on verbose output
  -q, --quit         suppress messages (expect error message)
  -p, --projects     show list of all active projects
  -P, --allprojects  show list of all projects (active and inactive)
  -h, --help         show this help message and exit
  --version          show the program version and exit

Commands:
  backup-clear    remove old backups
  backup-db       Create database backup. If no database name is specified
                  a backup of all databases will be created
  backup-files    Create backup of files
  backup-ls       List all available backups
  backup-rsync    Rsync backup files with remote system
  command-ls      List all available commands
  command         run commands
  init-system     initial a new system environment
  permission      set file and directory permissions
  release-create  Create a new release. If no project is specified, for all
                  projects a new release will be created
  release-ls      List all available releases
  reset-db        Reset database. If no project is specified, all active
                  project databases will be reseted
  reset-dir       Reset directory. If no project is specified, all active
                  projects files/directories will be reseted.
  rollout-all     Run rollout, rollout-system and permission plugins
  rollout-system  rollout system files/configuration
  rollout         rollout a new release
  setup-drupal    Setup a drupal installation
  status          status messages and information of vcdeploy environment
  system-log      log system changes
  sample          Meine Plugin-Beschreibung

Die Ausführung des neuen Plugins erfolgt nun mit folgendem Befehl:

vcdeploy -p sample

Fallbeispiele für den Einsatz

Deploy der Produktivumgebung

Produktv/Staging Datenbank auf Entwicklersystem übertragen

Pflege der Systemkonfiguration

Einfaches Aktualisieren mehrerer Repositories mit einem Befehl

Systemkonfigurationen protokollieren

Weitere Ressourcen

• vcdeploy Doxygen Dokumentation

Projektmanagement Services, Deployment Coaching und Consulting

Unser Projektmanagement Team aus München hat Experten für Drupal und PHP. Wir erstellen ein individuelles Konzept für das reibungslose Deployment Ihrer Plattform und helfen dabei, dieses in Ihrem Projekt umzusetzen. Kontaktieren Sie uns unverbindlich.