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:install Du bist ohnehin per SSH da. Der einzige Weg, der sich automatisieren lässt (--no-interaction)
Browser Domain auf /pfad/zur/installation/public zeigen lassen, dann /install aufrufen Die 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.