Erste Schritte
Installation
Voraussetzung: Datenbank und Domain stehen bereit.
1. Dateien auf den Server bringen
Auf dem Zielserver:
curl -fLO https://gitlab.com/mankeldor/formrelay/-/raw/main/formrelay-setup.sh
sh formrelay-setup.sh /pfad/zur/installation
Das Skript holt das neueste Release, prüft die Prüfsumme, entpackt es, installiert die
PHP-Abhängigkeiten und führt formrelay:check aus.
Sieh dir das Skript an, bevor du es ausführst.
| Option | Wirkung |
|---|---|
--dry-run |
Zeigt nur, was passieren würde |
--version vX.Y.Z |
Eine bestimmte Fassung statt der neuesten |
--token-file <datei> |
Zugangs-Token für ein nicht öffentliches Projekt |
--yes |
Ohne Rückfragen |
sh formrelay-setup.sh --help listet alle.
Das Skript sieht sich das Zielverzeichnis an: leer heißt Erstinstallation, eine erkennbare Formrelay-Installation heißt Aktualisierung, alles andere heißt Abbruch ohne Download und ohne Überschreiben.
Andere Wege: Release-Paket von Hand · Repository klonen · GitLab CI/CD
Hier endet das Skript
Es richtet nicht ein. Die Dateien liegen, die Abhängigkeiten sind installiert — die
.env, die Datenbank und der erste Administrator fehlen noch.Für die Einrichtung gibt es zwei gleichwertige Wege, beide in Schritt 3:
Weg Aufruf Wann Terminal cd /pfad/zur/installation && php artisan formrelay:installDu bist ohnehin per SSH da. Der einzige Weg, der sich automatisieren lässt ( --no-interaction)Browser Domain auf /pfad/zur/installation/publiczeigen lassen, dann/installaufrufenDie Domain steht bereits. Vier Schritte mit Erklärungen an jedem Feld Beide stellen dieselben Fragen und tun dasselbe. Was du nimmst, ändert nichts am Ergebnis.
Bei einer Aktualisierung entfällt das: Dort läuft das Skript vollständig durch.
2. Verzeichnisse und Rechte prüfen
Das Setup-Skript hat diese Prüfung schon ausgeführt. Auf den anderen Wegen und um einen Befund zu beheben:
php artisan formrelay:check
Fehlen Verzeichnisse:
mkdir -p storage/framework/views storage/framework/cache/data \
storage/framework/sessions storage/logs \
storage/app/private storage/app/public bootstrap/cache
Fehlt das Schreibrecht — <web-user> ist der Nutzer, unter dem PHP läuft (www-data,
nginx, bei Shared Hosting meist dein eigener):
chown -R <web-user>:<web-group> storage bootstrap/cache
chmod -R u+rwX storage bootstrap/cache
Der Befehl nennt in beiden Fällen die betroffenen Pfade und den passenden Aufruf.
3. Einrichten
Weg A: Kommandozeile
cd /pfad/zur/installation
php artisan formrelay:install
Prüft die Voraussetzungen, fragt Datenbank, Adresse, ersten Administrator und den
Mail-Versand ab und richtet ein. Der Mail-Versand wird sofort geprüft: Verbindung, dann eine
Test-Mail an den Administrator. Werte aus einer vorhandenen .env sind vorbelegt. Die
Kommandozeile ist englisch.
Ohne Rückfragen, für automatisiertes Deployment:
php artisan formrelay:install --no-interaction \
--db-database=formrelay --db-username=formrelay --db-password='…' \
--url=https://example.org \
--admin-name='Vorname Nachname' --admin-email=admin@example.org --admin-password='…' \
--mail-host=mail.example.org --mail-port=587 --mail-encryption=tls \
--mail-username=formrelay@example.org --mail-password='…' \
--mail-from-address=formrelay@example.org \
--update-check=false
Ohne Rückfragen braucht es entweder die Mail-Angaben oder ausdrücklich --skip-mail —
sonst bricht der Befehl ab, bevor er etwas verändert. Scheitert die Test-Mail, ist die
Installation trotzdem fertig, der Befehl endet aber mit Exit-Code 1; nach dem Korrigieren
prüft php artisan formrelay:mail-test erneut.
| Option | Wirkung |
|---|---|
--db-host=…, --db-port=… |
Nötig, sobald die Datenbank nicht auf 127.0.0.1:3306 liegt |
--db-prefix=… |
Tabellen-Präfix bei geteilter Datenbank |
--name=… |
Name der Installation |
--update-check=true|false |
Einmal täglich nach einem neueren Release sehen und einen Hinweis in den Systemdaten zeigen. Aktualisiert nichts. Vorgabe true. Baut eine Verbindung nach außen auf — in abgeschotteten Netzen false |
--update-source=… |
Woher die Release-Liste kommt. Nur nötig, wenn du eine eigene Fassung pflegst |
--mail-transport=smtp|sendmail |
Versandweg, Vorgabe smtp |
--mail-host=…, --mail-port=…, --mail-encryption=tls|ssl|none |
SMTP-Server |
--mail-username=…, --mail-password=… |
SMTP-Zugang; das Passwort liegt danach verschlüsselt in der Datenbank |
--mail-from-address=…, --mail-from-name=… |
Absender aller Mails. Ohne Name gilt der Name der Installation |
--skip-mail |
Mail-Versand später einrichten. Bis dahin wird keine Einsendung zugestellt; die Systemdaten erinnern daran |
--force |
Weitermachen, obwohl eine Installation erkannt wurde |
Beides landet als FORMRELAY_UPDATE_CHECK und FORMRELAY_UPDATE_SOURCE in der .env und
ist dort änderbar.
Weg B: Browser
Lass die Domain auf /pfad/zur/installation/public zeigen, rufe
https://example.org/install auf und folge den fünf Schritten: Voraussetzungen, Datenbank,
Administrator, E-Mail, fertig.
Im Schritt „E-Mail" prüft ein Button alles in der Reihenfolge, in der es scheitern kann: speichern, Verbindung aufbauen, Test-Mail an den Administrator. Scheitert etwas, bleibt der Zugang gespeichert und die Meldung des Servers steht da. Darunter stehen Hinweise zu SPF und DMARC der Absenderdomain. „Überspringen" geht, aber nur mit eigenem Button — bis ein Versandweg funktioniert, wird keine Einsendung zugestellt.
Im Schritt „Datenbank" steht neben den Zugangsdaten die vorbelegte Auswahl „Auf neue
Fassungen prüfen". Die Quelle der Release-Liste lässt sich nur in der .env ändern
(FORMRELAY_UPDATE_SOURCE).
Diese Adresse ist ohne Anmeldung erreichbar, solange kein Administrator existiert. Sobald der erste angelegt ist, antwortet sie mit 404. Lass eine frisch hochgeladene Installation nicht tagelang offen stehen.
4. Cron einrichten
Zwei Einträge, beide nötig: Cron einrichten.
5. Nach der Installation
Sieben Schritte in fester Reihenfolge, beginnend mit dem Mail-Versand: Nach der Installation.
Wenn etwas nicht läuft
| Symptom | Ursache |
|---|---|
/install antwortet mit 404 |
Es existiert bereits ein Administrator |
| Weiße Seite, keine Gestaltung | public/build/ fehlt. Assets bauen und hochladen |
500er, failed to open stream: Permission denied |
Ein Verzeichnis unter storage/ fehlt oder ist nicht beschreibbar. php artisan formrelay:check nennt es |
| Logo wird nicht angezeigt | public/storage fehlt: php artisan storage:link, oder von Hand verknüpfen |
| Zugangsdaten stimmen, werden aber abgewiesen | Ein # im Passwort in der .env. Wert in doppelte Anführungszeichen setzen |
| Änderungen wirken nicht | php artisan config:clear |
.env ist für alle lesbar |
chmod 640 .env |
Ausführlich: Störungssuche.
Quelle dieser Seite: docs/installation.md im Repository. Sie wird beim Bauen daraus erzeugt — Änderungen gehören in die
Markdown-Datei, nicht in diese Seite.