Basissystem Einrichten¶

Konfiguration¶

Alle Konfigurationsdaten des Colibri Basissystems befinden sich im Konfigurationsverzeichnis (config/). Jeder dieser Konfigurationsdateien ist mithilfe von DocBlock Kommentaren dokumentiert und sollte als Deine erste Anflaufstelle zum Gesammtüberblick des Basissystems dienen.

Verzeichnisschutz¶

Eventuell brauchen gewisse Verzeichnisse besondere Rechte. Nachfolgend findest Du die dazugehörigen Kommandos um die etwaigen Rechte korrekt zu vergeben:

sudo chgrp -R www-data storage/ bootstrap/cache/
sudo chmod -R ug+rwx storage/ bootstrap/cache/

Webserver¶

Lokaler PHP-Server¶

Falls Du bereits PHP-7 auf Deinem Rechner installiert hast, kannst Du mithilfe des serve Artisan Kommandos, einen lokalen Entwicklungsserver starten. Dabei versucht PHP das Basissystem unter der URL: http://localhost:8000 abzubilden. Eine Datenbank wird Dir dabei jedoch nicht zur Verfügung gestellt, lediglich Dein PHP steht zur Verfügung:

php artisan serve

Eine weit aus fortgeschrittenere Methode um eine Entwicklungsumgebung einzurichten, findest Du unter: Entwicklungsumgebung. Dieses Artisan Kommando sollte wirklich nur gebraucht werden um bspw. kurz einen Einblick auf die Startseite zu erhaschen, nicht jedoch um professionelle Webanwendungen zu kreiieren.

Pretty URL’s¶

Apache¶

Mithilfe der public/.htaccess Dateien werden alle Anfragen an den Front-Controller weitergeleitet, ohne dass Du die index.php Datei angeben musst. Damit diese Weiterleitung korrekt funktioniert musst Du jedoch gewährleisten dass das mod_rewrite Modules Deines Apache Webserver aktiviert wurde, ohne dieses Modul werden keine .htaccess Dateien von Deinem Webserver akzeptiert.

Falls die reguläre Lösung in public/.htaccess bei Dir nicht funktioniert kannst Du es mit nachfolgender Alternative versuchen:

Options +FollowSymLinks
RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

Nginx¶

Wenn Du hingegegen einen Nginx Webserver verwendest, kannst du folgende Konfiguration setzen, damit alle Anfragen korrekt an den Front-Controller weitergeleitet werden können:

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

Anwendungsschlüssel¶

Der Anwendungsschlüssel oder auch Application-Key genannt, ist eine willküllriche Zeichenkette, welcher zum verschlüsseln von Sessiondaten vewendet wird. Normalerweise handelt es sich um eine Zeichenkette (string) bestehend aus 32-Zeichen.

Bei der Installtion von Colibri sollte automatisch ein Anwendungsschlüssel generiert worden sein. Diesen Schlüssel findest Du in Deiner .env Datei (APP_KEY). Solltest Du einmal keinen Schlüssel vorfinden oder falls Du einen neuen Schlüssel generieren möchtest, kannst Du mithilfe des key:generate Artisan Kommando’s tun:

php artisan key:generate

Warnung

Sollte der Anwendungsschlüssel aus irgendwelchen Gründen fehlen, werden die Sessiondaten Deiner Benutzer nicht verschlüsselt und sind somit nicht sicher!

DotEnv-Konfigurationen¶

Oftmals möchte man Konfigurationen an der aktuellen Umgebung des Basissystems anpassen. So ist es bspw. möglich, dass Du ein komplett anderes Cache-System innerhalb der Entwickung verwenden möchtest als Du bspw. für die Produktion einsetzt.

Colibri greift dabei auf die DotEnv PHP Bibliothek von Lance Lucas zu, um solche umgebungsspezifische Variablen in einer .env Datei auszulagern. Bei einer frischen Colibri Installation wird die .env.dist Datei automatisch kopiert, umbenannt in .env und mit einem Schlüssel versehen; all diese Schritte sind dabei innerhalb der composer.json Datei beschrieben.

Da Du innerhalb der .env Datei Deine Zugangsdaten und geheimen Konfigurationen tätigst, solltest Du niemals die .env Datei im Versionskontrollsystem aufnehmen, um Deine Daten zu schützen. Colibri übernimmt diese Aufgabe bereits für Dich, indem der entsprechende Eintrag in der .gitignore Datei hinterlegt wurde.

Falls Du zusammen mit einem Team arbeitest, wird im Regelfall die .env.dist Datei als Orientierungspunkt für Teammitglieder verwendet. Dabei können bspw. Platzhalterwerte eingesetzt werden, um anderen einen Hinweis zu geben wie sie die Konfiguration zu definieren haben.

Eine weitere DotEnv Datei welche von Colibri verwendet wird ist bspw. die .env.testing. Diese Datei überschreibt die .env Datei beim Einsatz der Testumgebung (PHPUnit) oder beim Ausführen von Artisan Kommandos mit der --env="testing" Option.

Hinweis

Jede Umgebungsvariable innerhalb der .env Datei kann von externen Umgebungsvariablen, wie bspw. Server-Level oder System-Level abhängigen Umgebungsvariablen überschrieben werden.

Wartungsmodus¶

Sollte sich die Anwendung im Wartungsmodus befinden, werden alle Anfragen an eine bestimmte Seite weitergeleitet. Dies erleichtert Dir ein temporäres „abschalten“ des Basissystems während Du bspw. Updates ausführen oder Wartungsarbeiten vornimmst.

Colibri verfügt über eine eigene Middleware, welche überprüft ob sich das Basissystem im Wartungsmodus befindet. Sollte dieser Fall eintreffen wird eine MaintenanceModeException Exception ausgeworfen. Dabei werden alle Anfragen mit dem Statuscode 503 beantwortet und an die entsprechende Seite weitergeleitet.

Während des Wartungsmodus werden keine Aufgaben aus den Warteschlangen (Queues) abgearbeitet. Diese Aufgaben werden erst dann ausgeführt wenn sich das Basissystem nicht mehr im Wartungsmodus befindet.

Wartungsmodus Aktivieren¶

Das down Artisan Kommando erlaubt uns dabei das aktivieren des Wartungsmodus für das Basissystem:

php artisan down

Optional kannst Du auch eine Nachricht (message) und Wiederholungsversuch (retry), in Sekunden, innerhalb des down Artisan Kommandos beifügen. Der Nachrichtenwert (message) wird dabei als Protokoll- oder Ausgabenachricht verwendet und sollte den Klienten über die Wartungsarbeiten informieren. Die retry Option hingegegen erlaubt es eine Zeitspanne, zu definieren, wann die Wartungsarbeiten möglicherweise abgeschlossen sind. Die Antwort wird dabei als Retry-After HTTP Header definiert:

php artisan down --message="Datenbank wird aktualisiert." --retry=60

Die 503-Seite¶

Das Blade-Template für die 503-Seite findest Du unter: resources/views/errors/503.blade.php. Du kannst die Seite beliebig anpassen wie jede andere View des Basissystems. Der Webseite steht dabei eine eigenes Stylesheet zur Verfügung. Die Resourcen dieses Stylesheets findest du unter: resources/assets/sass/pages/503.sass. Vergiss nicht die Datei zu kompilieren, falls Du Änderungen innerhalb dieses Stylesheets tätigst.

Wartungsmodus Deaktivieren¶

Um den Wartungsmodus zu beenden kannst Du das up Arisan Kommando verwenden:

php artisan up

Alternativen zum Wartungsmodus¶

Da die Umschaltung des Basissystems in den Wartungsmodus eine gewisse Anzahl an Sekunden eine sogenannte Downtime verursacht, lohnt es sich nach Alternativen umzusehen, welche diese Probleme lösen. Eine Alternative ist hierbei Envoyer welche ohne Downtime solche veröffentlichungen vornehmen kann.