Ein Leitfaden zu Bedrock für WordPress

Der folgende Beitrag ist ein Gastbeitrag von Alessandro Vendruscolo, der mich voller Begeisterung kontaktierte, um einen Gastbeitrag über ein WordPress-Tool zu schreiben, von dem ich noch nicht viel wusste: Bedrock. Es ist kein Theme, sondern eine Methode, WordPress sicher und unter Berücksichtigung moderner Entwicklungspraktiken zu installieren, zu konfigurieren und zu verwalten.

Bedrock ist ein Open-Source-Projekt von Roots, das als Basis für WordPress-Projekte dient.

Warum sollten Sie sich für Bedrock interessieren? Treten wir einen Schritt zurück und denken wir über die typische Vorgehensweise bei der Arbeit an einem WordPress-Projekt nach.

Klassischer WordPress-Workflow

Sie können WordPress sowohl auf Ihrem lokalen Rechner als auch auf dem Produktionsserver herunterladen und installieren. Für Ihr Theme können Sie ein Git-Repository haben. Die Bereitstellung kann per FTP-Übertragung des Themes oder per Git-Pull des Repos vom Server erfolgen. Für einige Projekte möchten Sie vielleicht die gesamte Website (einschließlich der WordPress-Dateien) ebenfalls unter Git verwalten.

Dies hat Probleme

• Die Aktualisierung von WordPress/Plugins von der Produktion kann Ihre Produktionsseite beschädigen
• Sie müssen die Versionen von WordPress/Plugins manuell verfolgen
• Bereitstellungen können umständlich sein
• Die Konfiguration von WordPress ist schwierig, da die wp-config.php-Datei nicht unter Versionskontrolle stehen kann

Hier ist ein Beispiel, was ich meine. Sie aktualisieren ein Plugin lokal, weil Sie eine neue Funktion benötigen, die das aktualisierte Plugin bietet. Sie schreiben Code basierend auf dieser neuen Funktion. Nun ist es Zeit für die Bereitstellung. Sie

1. Installieren oder aktualisieren Sie das Plugin auf der Produktionsseite (stellen Sie sicher, dass es die gleiche Version ist!)
2. Kompilieren Sie Assets
3. Aktualisieren Sie das Theme auf dem Remote-Server (mit beliebiger Bereitstellungsmethode)
4. Wenn es sich um ein neues Plugin handelt, stellen Sie sicher, dass es auf der Produktionsseite aktiviert wurde

Dies ist ein eher manueller Ansatz und kann fehleranfällig sein. Vor allem kann es zu Ausfallzeiten oder fatalen Fehlern führen. Zum Beispiel aktualisieren Sie das Plugin und es ist nicht abwärtskompatibel, sodass es Fehler auslöst, bis die Bereitstellung abgeschlossen ist. Oder Sie stellen zuerst bereit und die Seite löst Fehler aus, bis Sie das Plugin aktualisieren.

Bedrock vorgestellt

Wenn Ihnen die oben genannten Probleme bekannt vorkommen, werden Sie Bedrock mögen. Es bringt

• Explizite Abhängigkeiten, die von Composer verwaltet werden
• Einfache Konfiguration mit phpdotenv
• Einfache Ein-Befehls-Bereitstellungen mit Capistrano

Sie erhalten ein in sich geschlossenes WordPress-Projekt, das eine explizite Version von WordPress und erforderliche Plugins installiert (composer install) und leicht konfiguriert werden kann. Die gesamte Konfiguration wird in einer .env-Textdatei gespeichert und bereitgestellt (cap production deploy).

Weniger Ärger und mehr Automatisierung! Selbst die Einarbeitung eines neuen Entwicklers wird einfacher.

Sie erhalten außerdem kostenlos eine mehrstufige Umgebung. Sie können eine development-Konfiguration für die lokale Arbeit, eine staging-Konfiguration für Tests und eine production-Konfiguration für die Live-Website haben. Sie können auch benutzerdefinierte Konfigurationen definieren, z. B. backup, wo Sie eine 1:1-Kopie der Produktionsumgebung auf einem anderen Server haben können.

Anforderungen

Hier sind die Voraussetzungen für die Arbeit mit Bedrock

• Sie sollten sich mit der Arbeit in der Kommandozeile wohlfühlen.
• Sie benötigen Shell-Zugriff auf den Server: Wenn Ihre Website auf einem Shared-Hosting-Anbieter gehostet wird, haben Sie wahrscheinlich Pech gehabt¹.
• PHP >= 5.5
• Sie benötigen Composer auf dem Server (Installationsanleitung).
• Sie benötigen eine funktionierende Ruby- und Gem-Umgebung auf Ihrem Rechner, um Bereitstellungen durchzuführen.
• Sie müssen WP-CLI lokal und auf dem Server installiert haben, wenn Sie es verwenden möchten. Es ist nicht zwingend erforderlich, aber Sie werden später sehen, dass es nützlich ist (Installationsanleitung).

Dies kommt zu allen normalen Serveranforderungen für WordPress hinzu, wie z. B. MySQL.

Erste Schritte

Gehen wir von einem brandneuen WordPress-Projekt aus. Zuerst benötigen Sie eine Kopie von Bedrock, die Sie aus dem Repository erhalten können.

Sollte ich das Repository klonen oder herunterladen?

Bedrock's README empfiehlt, das Repository zu klonen, aber meiner Meinung nach ist es besser, es herunterzuladen. Wenn Sie vorhaben, es regelmäßig auf dem neuesten Stand zu halten, wählen Sie die Klon-Methode; wenn Sie es einmal einrichten und dann vergessen möchten, wählen Sie die Download-Methode.

Bedrock aktuell zu halten ist sicherlich gut (Verbesserungen, Sicherheit usw.), kann aber knifflig sein. Sie müssen möglicherweise Änderungen manuell auswählen oder versuchen, zwei Upstreams zusammenzuführen. Da es sich um einen Ausgangspunkt handelt, bedeutet das Herunterladen, dass Sie es einmal einrichten und vergessen können.

Installation

Nachdem Sie das Repository heruntergeladen haben, können Sie Ihr eigenes Repository für das Projekt initialisieren.

wget https://github.com/roots/bedrock/archive/master.zip
unzip master.zip
rm master.zip
mv bedrock-master ~/Sites/example.dev
cd !$
git init

Ich speichere alle meine Webprojekte im Ordner Sites in meinem Home-Verzeichnis (ich entwickle unter OS X) und indexiere sie nach ihrem Namen. Ich verwende die .dev-TLD, damit ich Nginx mit virtuellen Hosts konfigurieren kann. Auf diese Weise habe ich auch bei der lokalen Entwicklung eine Konfiguration, die fast identisch mit der Live-Website ist. (Bonuspunkte im Vergleich zur Verwendung von localhost: Sie erhalten eine neue _Umgebung_ zum Arbeiten: Cookies, lokaler Speicher, URLs für Caching usw. werden nicht mit anderen Websites geteilt, an denen Sie zuvor gearbeitet haben.)

Auf meinem Rechner verwende ich diese minimale Konfiguration, um Nginx anzuweisen, wie die Website gehostet werden soll. Bitte beachten Sie, dass der Root-Ordner nicht derselbe ist wie der Projektordner. Bedrock legt alle öffentlichen Dateien im web-Ordner ab.

server {
  listen 80;
  server_name example.dev;

  root /Users/MJ/Sites/example.dev/web;

  location / {
    try_files $uri $uri/ /index.php;
  }

  location ~ .php$ {
    try_files $uri =404;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    include fastcgi.conf;
    fastcgi_intercept_errors on;
    fastcgi_pass unix:/tmp/php5-fpm.sock;
  }
}

Nun müssen wir einen Befehl ausführen, damit die Magie geschieht

composer install

Wie die Ausgabe zeigt, wird Composer die in der composer.lock-Datei aufgeführten Abhängigkeiten installieren, einschließlich WordPress selbst².

Was passiert also?

Wenn Sie neu bei Composer sind, erkläre ich kurz, was es ist und wie es funktioniert.

Composer ist ein in PHP geschriebenes Werkzeug, mit dem Sie PHP-Abhängigkeiten verwalten können (ähnlich wie Ruby Gems, npm-Module, CocoaPods usw.). Heutzutage haben alle Sprachen einen Abhängigkeitsmanager.

Sie deklarieren die von Ihnen benötigten Pakete in der composer.json-Datei und deklarieren sie dann mit Constraints. Constraints ermöglichen es Ihnen zu definieren, wie Composer sie aktualisieren soll, wenn Sie composer update ausführen.

Zum Beispiel erfordert Bedrock eine explizite Version für WordPress (zum Zeitpunkt des Schreibens 4.5) und jede Version
größer als 2, aber kleiner als 3 für phpdotenv.

Jedes Mal, wenn Sie composer update ausführen, versucht Composer, Ihre Pakete auf die neueste zulässige Version zu aktualisieren, und schreibt diese Versionsnummer in die composer.lock-Datei.

Wenn Sie nun composer install ausführen (genau wie zuvor), werden **diese spezifische Version installiert, unabhängig davon, was passiert**, indem aus der composer.lock-Datei gelesen wird (Dies ist ein Grund, warum die Verwendung von Composer sehr sicher ist, ähnlich wie bei Gem und CocoaPods, und im Gegensatz zu npm, es sei denn, Sie verwenden die Shrinkwrap-Funktion).

Wenn Sie nun den Inhalt des web- und des web/wp-Verzeichnisses auflisten, sehen Sie etwas Vertrautes: Composer hat die Datei wp-config.php in den Ordner web verschoben und alle WordPress-Dateien befinden sich im Ordner web/wp. Wenn Sie diese Datei überprüfen, können Sie verstehen, warum sie dort ist.

Wir haben alles eingerichtet, jetzt ist es Zeit, WordPress zu konfigurieren.

Kopieren Sie .env.example nach .env und bearbeiten Sie es

cp .env.example .env
vim .env

Es fragt Sie nach

1. Dem Namen der von Ihnen verwendeten Datenbank (ich verwende example_development)
2. Dem Benutzernamen, der für die Verbindung zur Datenbank verwendet wird (auf meinem Rechner habe ich nur einen root-Benutzer)
3. Dem Passwort dieses Benutzers
4. Dem Host der Datenbank (127.0.0.1 oder localhost ist in Ordnung)
5. Der Umgebung dieser Installation (development ist in Ordnung, Sie können beliebig viele einstellen: normalerweise haben Sie development, staging und production)
6. Die Homepage-URL, die WordPress unter anderem zum Erstellen von URLs verwendet (ich habe http://example.dev eingestellt)
7. Die URL für die Admin-Seite. Lassen Sie sie unverändert und Sie greifen auf die WordPress-Admin-Seiten unter http://example.dev/wp zu. Wenn Sie dies ändern, müssen Sie auch den Inhalt des wp-Ordners entsprechend verschieben.
8. Autorisierungsschlüssel und Salze, die Sie online generieren können

Nachdem Sie die Datei gespeichert haben, können Sie mit der Installation von WordPress fortfahren (es müssen alle Tabellen in der Datenbank erstellt werden!). Sie können dies tun, indem Sie die Website unter http://example.dev/ besuchen oder WP-CLI verwenden.

wp core install --url='http://example.dev' --title='Example' --admin_user='admin' --admin_password='enter' --admin_email='<admin_email>'

WordPress wurde erfolgreich installiert!

Wir können unsere Änderungen committen (git add . && git commit -m 'Erster Commit').

Fassen wir den Prozess zusammen

1. Bedrock herunterladen;
2. composer install ausführen;
3. Die Datei .env bearbeiten;
4. WordPress installieren (automatisiert mit dem Befehl wp core install …).

Wenn später andere Entwickler dem Team beitreten, klonen sie das Repository des Projekts und beginnen bei Schritt 2.

Arbeiten an Ihrem Projekt

An diesem Punkt haben wir eine Standard-WordPress-Installation und können mit der Anpassung beginnen!

Wenn wir die Ordnerstruktur untersuchen, sehen Sie, wie Bedrock die Dateien organisiert

.
├── config
│   ├── application.php
│   └── environments
│       ├── development.php
│       ├── production.php
│       └── staging.php
├── vendor
├── web
│   ├── app
│   │   ├── mu-plugins
│   │   ├── plugins
│   │   ├── themes
│   │   └── uploads
│   ├── wp
│   └── wp-config.php

• config: Hier konfigurieren Sie WordPress. Diese Dateien sind nicht aus dem Internet zugänglich, da wir Nginx so konfiguriert haben, dass es Dateien aus dem web-Ordner bedient.
  • config/application.php: Diese Datei enthält die übliche WordPress-Konfiguration und soll Basiseinstellungen enthalten, die für alle Umgebungen gelten.
  • config/environments/*: Diese enthalten umgebungsspezifische Einstellungen. Zum Beispiel deaktiviert es in der Produktion die Ausgabe von Fehlern.
• vendor: Abhängigkeiten, die von Composer verwaltet werden, werden dort installiert, mit Ausnahme von WordPress-Plugins und Themes; wenn Sie die Datei composer.json untersuchen, werden Sie sehen, dass diese Art von Paketen in web/app/{mu-plugins,plugins,themes}/ verschoben werden.
• web: Dateien, die in diesem Verzeichnis enthalten sind, sind öffentlich zugänglich
  — nur die benötigten Dateien befinden sich im web-Ordner (siehe config oben).
  • web/app: Dies ist der alte wp-content-Ordner. Er wurde umbenannt, um seinen Inhalt besser widerzuspiegeln (dies entspricht auch den Konventionen anderer Frameworks wie Rails und Symfony). Hier landen Ihre Plugins und Themes.
  • web/wp: Das gesamte WordPress-Paket. Dies sollte in vendor platziert werden, kann aber aufgrund von WordPress-Beschränkungen nicht.
  • web/wp-config.php: Diese Datei ist bekannt, aber in Bedrock fungiert sie als Loader (sie lädt Einstellungen aus dem config-Verzeichnis). Sie muss hier bleiben, da WordPress-Core-Pfade fest kodiert.

Konfiguration und Umgebungsvariablen

Wie wir bereits gesehen haben, haben wir mehrere Konfigurationsdateien im config-Verzeichnis und auch die .env-Datei, in der wir den Benutzernamen/das Passwort für die Datenbank hinterlegen.

Der Kernaspekt ist dieser: Wenn es sich um etwas handelt, das sensibel ist (ein Passwort oder ein Zugriffsschlüssel für einen externen Dienst), sollten Sie es in die .env-Datei aufnehmen und mit der Funktion env('<name>') auslesen. Sensible Informationen werden niemals in Ihrem Git-Repository gespeichert (die .env-Datei wird von Git ignoriert), was ein riesiger Vorteil ist. Es ermöglicht Ihnen auch, für jeden Rechner ein anderes Passwort/einen anderen Schlüssel zu definieren. Stellen Sie sich vor, jeder Entwickler muss seinen Twitter-Konsumschlüssel generieren oder einen neuen für Testzwecke generieren: Wenn der Schlüssel in einer von Git nachverfolgten Datei gespeichert ist, müssen Sie daran denken, diese Datei nicht in den Staging-Bereich aufzunehmen.

Die Lösung ist, es in die .env-Datei aufzunehmen

[…]
DB_PASSWORD=<password>
[…]

und diesen Wert in der Konfigurationsdatei zu lesen

define('DB_PASSWORD', env('DB_PASSWORD'));

Denken Sie daran, dass umgebungsspezifische Dateien (`config/environment/.php`) vor der Hauptdatei (`config/application.php`) benötigt werden. **Das bedeutet, dass Sie Einstellungen nicht überschreiben können**. Sagen Sie, dass Sie die gleiche Konfiguration für Entwicklung und Staging haben, aber eine andere für die Produktion. Sie können

• sie in jeder Umgebungsdatei definieren (`development.php`, `staging.php`, `production.php` usw.).
• sie in die .env-Datei aufnehmen und in der Hauptanwendungsdatei (`application.php`) definieren.

Plugins

Wenn Ihr Plugin im offiziellen Plugin-Verzeichnis verfügbar ist, können Sie es mit Composer und WordPress Packagist installieren, einem Composer-Repository, das das offizielle Plugin- und Theme-Verzeichnis von WordPress spiegelt.

Bedrock hat bereits das Repository von wpackagist hinzugefügt, sodass die Installation eines Plugins nur einen Befehl erfordert, um die neueste Version zu installieren

composer require wpackagist-plugin/<name>
git add composer.json composer.lock
git commit -m 'Install <name> plugin'

Plugins sind mit wpackagist-plugin/ vorangestellt, also wird das Plugin Memberful WP zu wpackagist-plugin/memberful-wp.

Sie können eine Einschränkung für die Version angeben (der vorherige Befehl würde die ^-Einschränkung verwenden)

composer require wpackagist-plugin/memberful-wp ~1.0
git add composer.json composer.lock
git commit -m 'Install Memberful plugin'

Sie können dasselbe erreichen, wenn Sie die Datei composer.json manuell bearbeiten und composer install ausführen.

Wenn Ihr Plugin nicht im offiziellen Verzeichnis verfügbar ist (wie benutzerdefinierte oder kostenpflichtige Plugins), müssen Sie es in `web/app/plugins` platzieren und aus der Ignorierliste entfernen.

mv ~/Downloads/my-plugin web/app/plugins/
echo '!/web/app/plugins/my-plugin' >> .gitignore
git add .gitignore web/app/plugins/my-plugin
git commit -m 'Add my AWESOME plugin'

Noch besser, wenn Sie ein Git-Repository für das Plugin haben, können Sie Composer direkt verwenden. Fügen Sie das Folgende zum Array repositories der Datei composer.json hinzu

{
  "type": "git",
  "url": "<repository url>"
}

Das Repository muss eine composer.json-Manifestdatei im Stammverzeichnis enthalten, wie diese

{
  "name": "macstories/wp-push-plugin",
  "description": "MacStories' implementation of Safari Push Notifications",
  "type": "wordpress-plugin",
  "license": "proprietary",
  "require": {
  "php": ">=5.5",
  "composer/installers": "~1.0.12"
  }
}

Wenn alles oben Genannte eingerichtet ist, können Sie composer require macstories/wp-push-plugin ausführen, um es zu installieren. Composer erwartet mindestens ein Git-Tag in diesem Repository.

Jetzt, da das Plugin vorhanden ist, können wir es aktivieren. Gehen Sie zur WordPress-Admin-Seite oder verwenden Sie erneut WP-CLI.

wp plugin activate memberful-wp

Diesmal benötigen wir nicht das Präfix wpackagist-plugin, da WordPress Composer nicht kennt.

Wenn Plugins Dateien oder Ordner erstellen müssen, sollten sie von Git ignoriert werden, indem sie in die Datei .gitignore aufgenommen werden. Ein Beispiel hierfür ist WP Super Cache: es erstellt zwei PHP-Dateien, die Einstellungen enthalten.

Wenn Plugins Sie bitten, die Datei wp-config.php zu ändern, verschieben Sie diese neuen Einstellungen in application.php (oder die umgebungsspezifische) wie oben erläutert.

Themes

Themes funktionieren genauso wie Plugins, mit zwei Unterschieden

1. Ihr Verzeichnis ist web/app/themes;
2. Der Vendor-Name von Composer ist wpackagist-theme.

Wenn Sie ein Theme verwenden, das im offiziellen WordPress-Verzeichnis verfügbar ist, können Sie es mit Composer installieren

composer require wpackagist-theme/activello

Wenn Sie Ihr eigenes Theme entwickeln, erstellen Sie dessen Ordner unter web/app/themes und Sie sind bereit. Es ist nicht notwendig, es aus der .gitignore-Datei auszuschließen.

In Ihrem Theme können Sie die aktuelle Umgebung abfragen und davon profitieren. Zum Beispiel auf MacStories (einer Website, die ich mit Bedrock entwickelt habe) binde ich die minimierten Assets nicht in development ein.

$main = '';
if (WP_ENV === 'development') {
  $main = macstories_asset_url( '/dist/main.css' );
} else {
  $main = macstories_asset_url( '/dist/main.min.css' );
}
// use the $main variable

Ein weiterer Unterschied ist die Analyse. Ich binde Mint Analytics nur in der Produktion ein, mit einem ähnlichen Ansatz wie oben. Google Analytics ist auch in Entwicklung oder Staging verfügbar, aber diese beiden Umgebungen verwenden eine andere Site-ID, sodass Tests einfacher durchzuführen sind.

WordPress aktualisieren

Zum Zeitpunkt des Schreibens ist WordPress bei Version 4.5.2. Nehmen wir an, Version 4.5.3 erscheint. Wir müssen die erforderliche Version ändern. Sie können die Datei composer.json bearbeiten und composer install ausführen oder einfach den folgenden Befehl ausführen

composer require johnpbloch/wordpress 4.5.1

Dadurch wird die Datei composer.json (und auch die Lock-Datei, da wir eine Abhängigkeit aktualisiert haben) aktualisiert und die Abhängigkeit installiert.

Normalerweise gibt es nach jedem WordPress-Update ein Datenbank-Schema-Upgrade, das Sie durch den Aufruf der WordPress-Admin-Seite durchführen können. Aber das ist mühsam, daher hat WP-CLI einen Befehl dafür

wp core update-db

Es gibt auch noch eine weitere Sache zu beachten, wenn Sie das Datenbank-Schema aktualisieren: Wenn Sie die Weboberfläche dafür verwenden und die Operation zu lange dauert, können Sie auf HTTP-Timeouts stoßen. WP-CLI überspringt die HTTP-Schicht und führt die Operationen aus, indem es PHP über die Befehlszeile ausführt, was keine Timeout-Probleme hat.

Plugins aktualisieren

Das AktualISIEREN von Plugins ist ähnlich wie das Aktualisieren von WordPress: Wenn Sie Composer zum Installieren verwendet haben, verwenden Sie Composer zum Aktualisieren.

Sie können composer require wpackagist-plugin/<name> <version> ausführen, um ein bestimmtes Plugin auf eine bestimmte Version zu aktualisieren, oder noch besser, composer update verwenden, um alle Pakete auf ihre neueste Version zu aktualisieren, die die Einschränkungen in der composer.json-Datei erfüllt.

Wenn Sie composer require <package> etwas (ohne eine Version anzugeben) ausführen, verwendet Composer standardmäßig die ^-Einschränkung: Wenn Sie composer update ausführen, wird das Paket auf die neueste Version aktualisiert, die keine neue Hauptversion ist. Ganz einfach.

Bereitstellung Ihres Projekts

An diesem Punkt sollten Sie eine funktionierende WordPress-Website auf Ihrem Rechner haben. Aber das ist fast nutzlos, es sei denn, Ihr Rechner ist mit dem Internet verbunden.

Capistrano ist das de-facto-Tool für Bereitstellungen und Sie können es verwenden, um WordPress-Websites bereitzustellen.

Was ist Capistrano?

Capistrano ist ein leistungsfähiges in Ruby geschriebenes Werkzeug, das hauptsächlich³ zur _Durchführung von Bereitstellungen_ verwendet wird. Ursprünglich wurde es zur Bereitstellung von Ruby on Rails Webanwendungen entwickelt, entwickelte sich aber weiter zur Bereitstellung jeder Art von Webanwendung, mit Plugins zur Ausführung benutzerdefinierter Aufgaben oder zur Verbindung mit externen Diensten.

Es gibt unzählige Anleitungen im Internet und viele Konferenzvorträge, aber um es zusammenzufassen: Capistrano verbindet sich über SSH mit Ihrem Server und folgt dann diesem Fluss, um _ein Repository_ auf dem Server zu aktualisieren und Aufgaben auszuführen. Sie fügen Haken bei jeder Aufgabe hinzu, um das zu tun, was Sie benötigen.

Es ist darauf ausgelegt, mit SSH-Schlüsseln zu arbeiten (so dass Sie keine Passwörter verwenden müssen) und es sollte sich als privilegierter Benutzer mit dem Server verbinden. Es kann sudo-Befehle ausführen, aber wenn Sie das tun müssen, ist wahrscheinlich etwas mit Ihrer Einrichtung falsch. Mehr dazu erfahren Sie auf der Dokumentationsseite Authentifizierung & Autorisierung. Ich verwende SSH-Agent-Weiterleitung, damit Capistrano über meinen lokalen SSH-Schlüssel vom Git-Host herunterladen kann.

Auf dem Server arbeitet Capistrano, indem es mehrere Verzeichnisse im Verzeichnis behält, das Sie als Ziel für Bereitstellungen festgelegt haben

.
├── current -> releases/20160420173015
├── releases
│   ├── 20160420173015
│   ├── 20160412113015
├── repo
└── revisions.log
├── shared

• current: Dies ist ein Symlink zur aktuell bereitgestellten Version (entweder die neueste oder eine frühere, wenn Sie zurückgerollt haben).
• releases: Bei jeder Bereitstellung erstellt Capistrano einen neuen Ordner mit einem Zeitstempel. Sie können die Anzahl der zu behaltenden Releases konfigurieren, und Capistrano räumt alte Releases auf (standardmäßig werden 5 Releases beibehalten).
• repo: Capistrano speichert das Repository auf dem Server und checkt die korrekte Revision auf dem Server aus — nichts wird von Ihrem Rechner auf den Remote-Server übertragen.
• revisions.log: Nach jeder Bereitstellung oder jedem Rollback wird dieses Protokoll aktualisiert.
• shared: Enthält Dateien und Ordner, die zwischen Releases geteilt werden müssen, wie z. B. Benutzer-Uploads.

Jede Bereitstellung wird isoliert ausgeführt und hat ihren eigenen Ordner im releases-Ordner. Wenn etwas schief geht, hat das keine Auswirkungen auf die aktuelle Version. Wenn es fertig ist, aktualisiert Capistrano den Symlink auf die gerade bereitgestellte Version.

In Ihrem Projekt haben Sie eine Capfile, die die auszuführenden Aufgaben anfordert (siehe Beispiel im Fluss) und eine deploy.rb-Datei, die Einstellungen enthält.

Wenn Sie Capistrano nicht verwenden möchten

Bedrock unterstützt Capistrano, aber es ist nicht zwingend erforderlich. Wenn Capistrano Sie nicht überzeugt oder Sie ein anderes Werkzeug bevorzugen oder gar kein Werkzeug verwenden möchten, sind Sie dazu frei.

Die einzige Anforderung ist, dass Sie composer install auf dem Server ausführen, damit Composer WordPress, Plugins und alle anderen Abhängigkeiten, die Ihre Website benötigt, herunterladen kann. Andernfalls haben Sie eine Art Zombie-Website mit nur Anwendungs-Code, aber nicht der Anwendung selbst.

Bereitstellung mit Capistrano

OK, ich habe Sie davon überzeugt, Capistrano auszuprobieren, legen wir los!

Das Roots-Team (das Team hinter Bedrock) hat ein separates Repository erstellt, um die Capistrano-Integration für Bedrock zu hosten. Das liegt daran, dass Capistrano von Bedrock nicht _erforderlich_ ist, sondern jederzeit hinzugefügt werden kann.

Erstellen oder bearbeiten Sie eine Datei Gemfile im Stammverzeichnis des Projekts und fügen Sie diesen Inhalt ein

source 'https://rubygems.org'

group :deployment do
  gem 'capistrano', '~> 3.4'
  gem 'capistrano-composer'
  gem 'capistrano-wpcli'
end

Führen Sie nun bundle aus, um die Gems zu installieren. Dies unterscheidet sich geringfügig von Roots' Einrichtung, da wir diese Gems in die Gruppe deployment gruppiert und auch die WP-CLI-Erweiterung installiert haben.

Capistrano wird von Bundler installiert und als Abhängigkeit behandelt, so wie wir es zuvor mit WordPress und Composer gemacht haben. Das ist nützlich, da jedes Projekt eine andere Version von Capistrano verwenden kann und nicht von einer global installierten Version abhängig ist. Auch wenn mehrere Entwickler im Team arbeiten, sorgt eine lokal installierte (und synchronisierte) Version von Capistrano dafür, dass alles so reibungslos wie möglich verläuft⁴.

Committen Sie sowohl Gemfile als auch Gemfile.lock – genau wie bei Composer.

git add 'Gemfile*' && git commit -m 'Install Capistrano'

Nun müssen wir Capistrano einrichten. Die Konfiguration von Capistrano wird im Git-Repository aufbewahrt. Sie müssen die Datei Capfile und den Inhalt des Verzeichnisses config aus dem Repository kopieren. Dies entspricht der Ausführung von bundle exec cap install und der Bearbeitung der Konfigurationsdateien von Capistrano.

Da wir auch das WP-CLI-Plugin installiert haben, müssen wir es in der Capfile aufrufen. Fügen Sie die folgende Zeile nach dem Aufruf des Composer-Plugins hinzu

require 'capistrano/wpcli'

Bearbeiten Sie config/deploy.rb und setzen Sie die Variablen :application und :repo_url und entfernen Sie die Zeile :deploy_to. Wenn Sie möchten, können Sie hier auch andere Einstellungen ändern. Es gibt viele Code-Kommentare und die Dokumentation ist großartig.

Die Variablen :linked_files und :linked_dirs sind wichtig. Wenn Sie sich von früher erinnern, erstellt Capistrano auf dem Server einen shared Ordner (der zwischen Deployments geteilt wird). Standardmäßig werden wir die `.env`-Datei und den Ordner `web/app/uploads` teilen.

Die `.env`-Datei enthält Anwendungs-Einstellungen und muss geteilt werden, damit die Website funktioniert, und auch, weil diese Datei nicht unter Versionskontrolle steht. Der Ordner `web/app/uploads` ist der *alte* Ordner `wp-content/uploads` und muss geteilt werden, da sonst Uploads nur innerhalb eines Releases existieren würden.

Den Rest der Datei config/deploy.rb können Sie wahrscheinlich ignorieren. Nach Zeile 22 werden zwei benutzerdefinierte Aufgaben definiert. Die erste ist leer und standardmäßig deaktiviert. Sie kann beispielsweise zum Neustarten des Webservers verwendet werden. Wenn Sie etwas haben, das nach einem Deployment neu gestartet werden muss, aktualisieren Sie die Aufgabe und aktivieren Sie sie.
Die zweite Aufgabe wurde vom Roots-Team hinzugefügt und ist standardmäßig deaktiviert. Sie wird verwendet, um die Optionen stylesheet_root und template_root von WordPress zu aktualisieren. Ich hatte noch nie einen Grund, sie zu ändern.

Bearbeiten Sie die Datei `config/deploy/<<stage>>.rb`, um Einstellungen pro Stage festzulegen.

Sie müssen die Einstellung server aktualisieren, da die Produktionsumgebung wahrscheinlich auf einem anderen Server als die Staging-Umgebung liegt.

Wir werden die Einstellung des Pfades :deploy_to hierher verschieben, da Ihr Staging-Pfad wahrscheinlich anders ist als der Produktionspfad. Sie können auch Einstellungen überschreiben, die in der Hauptdatei `deploy.rb` festgelegt wurden. Die Logik dieser Dateien ist dieselbe wie bei den Bedrock-Umgebungsdateien.

Jetzt haben wir Capistrano konfiguriert und alles *sollte* funktionieren. Capistrano verfügt über eine check-Aufgabe, die, nun ja, prüft, ob alles funktioniert.

Führen Sie den folgenden Befehl aus, um die Prüfung durchzuführen

bundle exec cap staging deploy:check

Capistrano wird

1. Sich mit dem von Ihnen definierten Benutzer auf dem Server anmelden (damit Sie sicher sind, dass die SSH-Verbindung funktioniert)
2. Remote-Dateien des Repositories auflisten (damit Sie wissen, dass Capistrano eine Verbindung zum Git-Host herstellen und sich authentifizieren kann)
3. Die Verzeichnisstruktur erstellen
4. Verlinkte Ordner erstellen
5. Auf verlinkte Dateien prüfen

Hier ist ein Beispiel für einen Capistrano-Fehler, den wir sehen könnten

FEHLER: Verlinkte Datei /path/to/:deploy_to/shared/.env existiert nicht auf <host>

Erstellen Sie diese Datei (Sie können `scp .env @:/shared/.env` verwenden, um Ihre Entwicklungs-`.env`-Datei auf den Server hochzuladen. Zu diesem Zeitpunkt interessiert uns, *dass* die Datei existiert, nicht, dass sie die *richtige* Datei ist) und wenn Sie fertig sind, überprüfen Sie erneut, ob alles funktioniert. Hurra, es funktioniert!

Pushen Sie Ihre Änderungen (andernfalls klont Capistrano ein leeres oder altes Repository) und führen Sie das Folgende aus, um ein *echtes* Deployment durchzuführen

bundle exec cap <stage> deploy

Dies ist der Befehl, den Sie sich merken und jedes Mal ausführen müssen, wenn Sie Ihre Website bereitstellen möchten.

Die Remote-WordPress-Konfiguration

Sie müssen die `.env`-Datei auf dem Remote-Server aktualisieren, um die korrekten Datenbankinformationen und vor allem die Einstellungen WP_ENV und WP_HOME festzulegen.

Wenn Sie in die Produktion bereitgestellt haben, muss dies WP_ENV=production sein (ich kenne Ihren WP_HOME-Wert nicht).

Ihr Webserver muss Inhalte aus dem Ordner current ausliefern, also wenn Sie lokal diese Einstellung für nginx hatten

root /Users/MJ/Sites/example.dev/web;

auf dem Server müssen Sie sie auf diese Weise aktualisieren

root <value of :deploy_to>/current/web;

Die Installation von WordPress auf dem Remote-Server ist lediglich eine Frage der Durchführung derselben Dinge, die Sie auf Ihrem lokalen Rechner getan haben. Sie können die Weboberfläche verwenden oder WP-CLI, sogar innerhalb von Capistrano.

Wenn Sie eine neue Version bereitstellen und in dieser Version ein neues Plugin installieren, können Sie den folgenden Befehl verwenden, um das Plugin zu aktivieren

bundle exec cap <stage> wpcli:run['plugin activate <name>']

Für Datenbankmigrationen

bundle exec cap <stage> wpcli:run['core update-db']'

Hooks

Sie können benutzerdefinierte Aufgaben für Capistrano definieren, aber bevor Sie dies tun, suchen Sie nach einer bestehenden Lösung. Capistrano verfügt über viele offizielle Plugins, wie Bundler, npm und viele andere von der Community getriebene Plugins.

Sagen wir zum Beispiel, Sie haben ein Build-Skript, das Sass-Assets kompiliert. Aufgrund der Vorteile, über die wir früher gesprochen haben, sollten Sie Sass in der Gemfile mit

gem 'sass', '~> 3.4'

Jetzt müssen wir zwei Dinge tun, wenn wir bereitstellen

1. Sicherstellen, dass das Sass-Gem installiert ist
2. Unser eigenes Build-Skript ausführen

Capistrano-Bundler

Der erste Schritt ist einfach zu erreichen: Wir werden das capistrano-bundler-Gem anfordern, indem wir diese Zeile zur Gruppe :deployment hinzufügen

gem 'capistrano-bundler', '~> 1.1.2'

Danach führen Sie bundle aus, um das Gem zu installieren und bearbeiten Sie auch die Capfile, um es anzufordern

require 'capistrano/bundler'

Fertig. Jedes Mal, wenn wir bereitstellen, führt Capistrano bundle install auf dem Server aus, nach der Aufgabe deploy:updated.

Wenn Sie möchten, setzen Sie die Variable :bundle_without in der Datei `deploy.rb`

set :bundle_without, %w{deployment development test}.join(' ')

Dadurch werden diese Gem-Gruppen von der Installation ausgeschlossen. Bundler wird weniger Gems installieren (die wir nicht brauchen werden!) und unsere Deployments werden schneller.

Ausführen benutzerdefinierter Skripte

Ich weiß nicht, wie Ihr Build-Skript strukturiert ist. Ich bin ein Fan von make, aber Sie können alles haben, was Sie wollen: ein Shell-Skript, npm-Skripte, Grunt/Gulp-Aufgaben usw. Egal was, wir müssen sie ausführen, sonst hat Ihre Website keine Assets.

Wir können ganz einfach eine benutzerdefinierte Aufgabe erstellen. Erstellen Sie Ihre `.cap`-Datei (z. B. `make.cap`) in `lib/capistrano/tasks`, damit sie automatisch geladen wird (andernfalls müssten Sie sie explizit aus der Capfile anfordern) mit diesem Inhalt

namespace :make do
  desc "Runs make all"
  task :all do
  on roles :all do
    within release_path do
    execute :make
    end
  end
  end

  before 'deploy:updated', 'make:all'
end

Capistrano wird unsere Aufgabe vor der Aufgabe deploy:updated ausführen. Da wir den Teil within release_path do … verwendet haben, wird dieser Befehl im korrekten Verzeichnis release/<<timestamp>> ausgeführt, das Capistrano bereitstellt.

Schauen Sie sich die Capistrano-Dokumentation für mehr an. Heißer Tipp: Achten Sie darauf, vor jedem Argument einen Doppelpunkt zu verwenden (dies hat mit Shell-Escaping zu tun).

Eine neue Stufe hinzufügen

Bedrock kommt mit drei Standardumgebungen

1. Entwicklung (nur Bedrock)
2. Staging (Bedrock und Capistrano)
3. Produktion (Bedrock und Capistrano)

Sie können bei Bedarf eine neue Stufe hinzufügen. Ein Beispiel wäre eine backup-Umgebung, die zu 100 % mit der production-Umgebung übereinstimmt. Die Datenbank könnte periodisch synchronisiert werden, oder Sie könnten eine MySQL-Replikationsfunktionalität einrichten. Im Fehlerfall würden Sie Ihre DNS auf einen anderen Host umleiten, und niemand wird etwas bemerken.

Um eine neue Stufe hinzuzufügen

1. Erstellen Sie eine neue Umgebung für Bedrock: `config/environment/backup.php` (Sie können eine vorhandene kopieren und bei Bedarf aktualisieren)
2. Erstellen Sie die Capistrano-Stufenkonfiguration: `config/deploy/backup.rb` (verwenden Sie auch hier eine vorhandene als Basis)
3. Richten Sie den Server ein (Webserver, Datenbank usw.)
4. Stellen Sie das Projekt bereit (bundle exec cap backup deploy:check und bundle exec cap backup deploy)
5. Stellen Sie sicher, dass die `.env`-Datei WP_ENV=production enthält

Migration eines bestehenden Projekts zu Bedrock

In diesem Tutorial haben wir ein *neues* Projekt erstellt, aber Bedrock kann auch mit bestehenden Projekten verwendet werden.

Wenn Sie eine bestehende WordPress-Website haben und diese nach Bedrock konvertieren möchten, können Sie sie so behandeln, als wäre es ein neues Projekt

1. Bedrock installieren
2. WordPress konfigurieren
3. Ihr Theme wiederherstellen
4. Plugins mit Composer installieren

Wenn Sie die WordPress-Core-Dateien nicht geändert haben, sind Sie fertig. Wenn Sie die WordPress-Core-Dateien geändert haben, müssen Sie Ihre benutzerdefinierte WordPress-Version unter Versionskontrolle halten (Sie verlieren einfache, Composer-gesteuerte WordPress-Updates, haben aber weiterhin alle anderen Funktionen).

Haken und Tipps

Einige Tipps

1. Denken Sie daran, dass Sie Dinge, die von anderen Dingen erstellt wurden, nicht selbst verwalten sollten. Dazu gehören beispielsweise: von Plugins erstellte Dateien, von einem Paketmanager installierte Dateien, von Benutzern hochgeladene Dateien usw. – fügen Sie sie nicht zu Git hinzu. Wenn Sie sie ignorieren, ist die Wahrscheinlichkeit hoch, dass sie in die Einstellung linked_files von Capistrano gehören.
2. Speichern Sie keine sensiblen Informationen in Git.
3. Vergessen Sie nicht, git push vor dem Deployment auszuführen: Ich habe mehrmals dieselbe Version bereitgestellt, bevor ich merkte, dass ich vergessen hatte zu pushen (auf dem Server zog Capistrano immer wieder dieselbe Version).
4. Verwenden Sie WP-CLI wann immer möglich: Es ist schneller und kann von Capistrano ausgeführt werden. Beispiele sind
   • wp plugin activate <name>
   • bundle exec cap <stage> wpcli:run['plugin activate <name>']
   • wp core update-db
   • bundle exec cap <stage> wpcli:run['core update-db']
5. Sie können den Capistrano-Branch (config/deploy.rb) auf set :branch, ENV['BRANCH'] || :master setzen: Dadurch können Sie einfach einen Branch bereitstellen, indem Sie BRANCH=my-feature bundle exec cap <stage> deploy ausführen (vergessen Sie nicht zu pushen, siehe Tipp Nr. 3); wenn Sie die Umgebungsvariable BRANCH=<branch> nicht angeben, greift Capistrano auf den Master-Branch zurück.
6. Mit Slackistrano können Sie nach jedem erfolgreichen Deployment einen Beitrag auf einem Slack-Kanal posten.

Zusammenfassung

Ich hoffe, Sie sind diesem Tutorial gefolgt und hatten Spaß daran. Ich ermutige Sie, eine neue Website auf Ihrem lokalen Rechner zu erstellen, um etwas zum Experimentieren zu haben.

Zusammenfassend lässt sich sagen, dass dies die Vorteile sind, die Bedrock bietet

• Eigenständiges Repository
• Einfache Deployments
• Einfache Multi-Stage-Unterstützung
• Mehr Konsistenz zwischen den Umgebungen
• Trennung zwischen Konfigurationsdateien und allem anderen

Glückwunsch zum Durchhalten dieses Tutorials. Entschuldigung, wenn es lang und schwierig war. Es ist definitiv nichts für Anfänger! Hoffentlich haben Sie unterwegs neue Werkzeuge kennengelernt und Ihr Verständnis für all die verschiedenen beweglichen Teile vertieft.

Die Vorteile einer solchen Arbeitsweise sind meiner Meinung nach die Mühe wert. Jetzt erstellen Sie etwas Schönes!

---

[^1]: Das liegt nicht daran, dass Sie nicht ssh <user>@<host> können (manche Hosts erlauben das), sondern daran, dass Sie einige der erforderlichen Software nicht installieren können – wenn Sie ein Skript verwenden, das auf dem Server läuft, um Assets zu erstellen, sind Sie *wahrscheinlich* in Ordnung.

[^2]: Leider gibt es derzeit keine offizielle Version von WordPress, die über Composer verteilt wird. Bedrock verwendet diesen Fork, der alle 15 Minuten synchronisiert.

[^3]: Tatsächlich können Sie mit Capistrano bereitstellen, was Sie wollen: Sie sind nicht auf Webanwendungen beschränkt, Sie könnten iOS-Apps auf einem Remote-Server bereitstellen, wenn das für Sie sinnvoll ist.

[^4]: Später sehen Sie `cap`-Befehle, denen `bundle exec` vorangestellt ist: Dies stellt sicher, dass das lokale Gem anstelle eines global installierten Gems verwendet wird (das möglicherweise nicht existiert). Dasselbe sollten Sie für Sass oder jedes andere Gem tun.