Files
fewo-stommer/docs/DEPLOYMENT.md
T
Lars Stommer f5d8be5eaf
Deploy FeWo mit PipelineManager / deploy (push) Failing after 1m59s
FeWo-Pilot mit freigegebenem PipelineManager 0.1.1 ausführen
2026-10-26 14:43:58 +01:00

11 KiB
Raw Blame History

Deployment auf Strato

Stand: 26.10.2026 · Gemeinsamer Manager: PipelineManager · Pilotkonfiguration: pipeline.toml · CI: .gitea/workflows/deploy.yml

1. Prinzip

Gitea (develop/main) ──► PipelineManager-Container auf Raspi5-Paperless
                       │ exakter Git-Commit · Abhängigkeiten · Tests · fertige Assets
                       │  tar.gz
                       ▼  SSH
Strato  <DEPLOY_PATH>/
          releases/20261022…/   ◄─ entpackt
          shared/.env            ◄─ einmalig von Hand
          shared/storage/        ◄─ Uploads, Logs, Sessions (bleiben)
          current ──► releases/… ◄─ atomar umgeschaltet nach migrate + optimize
          .htaccess ──► releases/<aktiv>/public  (Domain-Zielverzeichnis = <DEPLOY_PATH>)
                       │
                       ▼  https://…/up  – Gesundheitscheck, bei Fehler automatischer Rollback

Auf dem Server werden nur bash, tar und PHP-CLI gebraucht – kein Composer, kein Node, kein Git, kein rsync.

Die Werkzeugumgebung wird im eigenen Repository C:\dev\pipelinemanager entwickelt und als lokales Image pipeline-manager:0.1.0 auf dem Pi freigegeben. Das Image bleibt nach dem Entfernen eines Job-Containers erhalten. Der Ablauf folgt Tsumugus Docker-Aufträgen auf dem vorhandenen Host-Runner (ubuntu-latest), führt Tests jedoch am exakten Commit vor dem Upload aus. Keine PHP-/Node-Installation auf dem Host und kein Build auf dem Entwicklungsrechner für automatische Deployments.

FeWo definiert nur seine prepare/test/finalize-Befehle, erforderlichen Dateien, Laravel-Hooks, persistenten Pfade und Ziele in pipeline.toml. Gemeinsame Paket-, Sicherungs-, Upload- und Rückfalllogik liegt im PipelineManager. Der bisherige manuelle Weg über scripts/deploy.sh bleibt als bestehender Wartungsweg erhalten, bis die neue Anbindung vollständig auf Test bestätigt ist.

2. SSH oder SFTP?

Empfehlung: SSH. Das Skript führt nach dem Hochladen Befehle auf dem Server aus (Archiv entpacken, Datenbank migrieren, Caches erzeugen, Version umschalten, ggf. zurückschalten). Das geht nur mit SSH.

Nur mit SFTP wäre ein Deployment möglich, aber deutlich schwächer:

  • Kein Entpacken auf dem Server → jede Datei einzeln übertragen (über 10.000 Dateien, mehrere Minuten pro Update, unterbrechungsanfällig).
  • Migrationen und Caches müssten über einen gesicherten Web-Aufruf angestoßen werden; kein artisan für Wartung und Fehlersuche.
  • Umschalten wäre per SFTP-Symlink möglich, aber ohne sauberen Rückfall bei Fehlern.

Strato richtet beide Zugänge im selben Menü ein (Kundenlogin › Datenbanken und Webspace › SFTP & SSH). Bei Hosting Pro sollte SSH enthalten sein – bitte dort prüfen. Falls nicht: Bescheid geben, dann ergänze ich einen SFTP-Modus.

3. Einmalige Einrichtung bei Strato

  1. PHP-Version auf 8.4 stellen (Datenbanken und Webspace › PHP-Version).
  2. SSH-Zugang anlegen (SFTP & SSH, Protokoll „SFTP + SSH“); Benutzername und Server aus „Details“ notieren – der Server ist paketspezifisch (z. B. 12345678.ssh.w1.strato.hosting), nicht ssh.strato.de. Eigenen SSH-Schlüssel hinterlegen oder einmalig ssh-copy-id -i ~/.ssh/strato_fewo.pub <benutzer>@<server>.
  3. Per SSH prüfen:
    ssh <benutzer>@<server>
    ls /opt | grep RZphp        # PHP-CLI-Pfad, z. B. /opt/RZphp84/bin/php-cli
    /opt/RZphp84/bin/php-cli -v
    
  4. Datenbank MariaDB 11.8 anlegen (Datenbanken verwalten; nicht MySQL 8.0 – Support endete im April 2026); Host, Name, Benutzer, Passwort notieren. In shared/.env: DB_CONNECTION=mariadb.
  5. Lokal scripts/deploy.example.env nach scripts/deploy.production.env kopieren und ausfüllen (wird nicht committet).
  6. bash scripts/deploy.sh production setup – legt die Ordner an und zeigt die PHP-Version.
  7. .env.production.example ausfüllen (u. a. APP_KEY via php artisan key:generate --show, Datenbank, SMTP/IMAP-Passwort, Tokens) und auf den Server nach <DEPLOY_PATH>/shared/.env kopieren (z. B. per SFTP).
  8. Erstes Deployment: bash scripts/deploy.sh production deploy
  9. Ersteinrichtung der Daten und erster Admin:
    bash scripts/deploy.sh production artisan db:seed --class=ProductionSeeder --force
    bash scripts/deploy.sh production artisan make:filament-user
    
  10. Domain-Zielverzeichnis auf den Ordner <DEPLOY_PATH> selbst setzen (Strato kann kein Symlink-Ziel wählen). Die .htaccess dort (von setup und bei jedem Umschalten neu geschrieben) leitet alles intern nach releases/<aktive Version>/public – bewusst nicht über den Symlink current, weil der OPcache von Strato Skripte unter dem Symlink-Pfad zwischenspeichert und sonst nach dem Umschalten die alte Version ausliefert. Sie sperrt interne Dateien (403) und setzt per AddType application/x-httpd-php84 .php die Web-PHP-Version nur für diesen Ordner auf die CLI-Version – andere Anwendungen im Paket bleiben unberührt. SSL-Zertifikat für die Domain aktivieren.
  11. Cronjob (Kundenlogin › Cronjobs), jede Minute:
    /opt/RZphp84/bin/php-cli <home>/<DEPLOY_PATH>/current/artisan schedule:run
    
    Falls Cronjobs nicht minütlich möglich sind: FEWO_SCHEDULER_TOKEN setzen und n8n jede Minute GET https://…/automation/scheduler?token=… aufrufen lassen.
  12. Überwachung: n8n alle 5 Min. GET https://…/health/sync?token=<FEWO_HEALTH_TOKEN> (200 = ok, 503 = Störung).

Testbetrieb zuerst: Für eine Subdomain (z. B. test.fewo-stommer.de) eine zweite Konfiguration scripts/deploy.staging.env mit eigenem DEPLOY_PATH, eigener Datenbank und eigenem shared/.env anlegen; bash scripts/deploy.sh staging deploy.

4. Tägliche Nutzung

Aufgabe Befehl
Neue Version ausliefern bash scripts/deploy.sh production deploy (baut den letzten Commit)
Bestimmten Stand ausliefern bash scripts/deploy.sh production deploy <commit oder tag>
Zurück zu einer früheren Version bash scripts/deploy.sh production releases zeigt die Deploy-Tags; dann bash scripts/deploy.sh production deploy deploy/production/<zeitstempel> (Migrationen werden nicht zurückgenommen)
Sofort zurück, solange die alte Version noch auf dem Server liegt (nur während eines laufenden Deployments) bash scripts/deploy.sh production rollback

Versionsgeschichte in Gitea statt auf Strato: Strato begrenzt die Anzahl der Dateien im Paket (eine Version ≈ 15.000 Dateien). Auf dem Server liegt deshalb nur die aktive Version, während eines Deployments kurz zusätzlich die neue. Die alte wird erst gelöscht, wenn die neue den Gesundheitscheck bestanden hat – schlägt er fehl, wird automatisch zurückgeschaltet. Jede erfolgreiche Auslieferung wird als Tag deploy/<umgebung>/<zeitstempel> in Gitea festgehalten; ein Build ist durch composer.lock/package-lock.json reproduzierbar. Außerdem entfernt der Build Sprachdateien außer de/en sowie Tests/Doku aus vendor (~4.800 Dateien weniger). | Artisan auf dem Server | bash scripts/deploy.sh production artisan about |

Windows: in Git Bash ausführen; COMPOSER_BIN="php /c/…/composer.phar" in der .env-Datei des Deployments setzen, falls composer nicht im PATH ist.

5. Automatisch über Gitea Actions

  • Push auf develop: Manager-Image prüfen, FeWo vorbereiten und die Feature-Suite im Container ausführen, danach nach test.fewo-stommer.de/ unter https://stommer.info deployen. Merge-Commit von develop nach main: derselbe Ablauf für prod.fewo-stommer.de/, sobald dieses Ziel ausdrücklich in pipeline.toml aktiviert ist.
  • Produktion ist derzeit enabled=false: Der Workflow überspringt Vorbereitung und Deployment. Eigenständige Produktionsdatenbank, .env und Domain-Zuordnung müssen vor Freigabe eingerichtet werden. Das bestehende WordPress-Verzeichnis www.fewo-stommer.de/ bleibt unangetastet.
  • Die 18 Manager-Tests liegen im separaten Repository; die Anwendung behält ihre 285 Feature-Tests. Kein setup-php, kein setup-node, keine Toolinstallation auf dem Pi-Host. Der bisherige Node-24-/PHP-Setup-Fehler entfällt damit.
  • Build und Deployment laufen in getrennten Containeraufrufen mit UID/GID des Runners und Ressourcenlimits. Nur der Deployment-Container erhält die Strato-Zugänge. Er bekommt weder den Docker-Socket noch Verzeichnisse anderer Anwendungen.
  • Persistente Verzeichnisse auf dem Pi: /home/lars/docker/pipeline-manager/cache (Composer/npm) und backups/<project>/<environment> (Datenbank, Medien und Server-Konfiguration). Backups werden vor dem Upload geprüft; ein Fehler verhindert die Auslieferung. Eine Sperre auf Strato verhindert parallele Umschaltungen desselben Ziels.
  • Repository-Secrets sind eingerichtet: DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY (eigener Pipeline-Schlüssel), DEPLOY_KNOWN_HOSTS (geprüfter Hostschlüssel). Geheimnisse bleiben außerhalb von Image und Repository. Der Manager schreibt sie nur vorübergehend in geschützte Dateien.
  • Die auf dem Pi freigegebene Image-Version muss vor dem FeWo-Workflow vorhanden sein. Für weitere Runner mit anderer Architektur ist eine entsprechende Imagebereitstellung erforderlich. Erst nach erfolgreichem Pilotlauf wird der alte manuelle Deploy-Weg ersetzt.

6. Getestet / offen

  • Lokal im Testmodus (DEPLOY_HOST=local) erfolgreich: Build (~19 MB), Upload, Entpacken, alle Migrationen auf frischer Datenbank, optimize, Ersteinrichtung per ProductionSeeder, alle Seiten und Admin-Login liefern 200.
  • Nicht unter Windows prüfbar: der Symlink-Wechsel von current (Git Bash legt Kopien statt Symlinks an). Unter Linux (Strato) ist das Standardverhalten; der erste Lauf auf dem Testbetrieb bestätigt es – bei Fehler greift der automatische Rollback.
  • Auf Strato erfolgreich (22.10.2026, test.fewo-stommer.de): SSH mit Schlüssel (paketspezifischer Server), PHP-CLI /opt/RZphp84/bin/php-cli, Migrationen auf MariaDB, Symlink-Umschaltung, .htaccess-Weiterleitung, Web-PHP 8.4 per AddType, ProductionSeeder; alle Seiten 200.
  • Testbetrieb läuft unter https://stommer.info (Domain-Ziel: Ordner test.fewo-stommer.de; SSL für Subdomains ist im Paket nicht verfügbar). Gesundheitscheck über HTTPS mit automatischem Rollback funktioniert.
  • Behoben: OPcache lieferte nach dem Umschalten die alte Version (→ .htaccess zeigt auf den konkreten Release-Ordner); URLs mit /current/public (→ URL::forceRootUrl(APP_URL) außerhalb von local/testing).
  • Noch offen: Cronjob.
  • Erstes Deployment auf ein neues Ziel: SKIP_HEALTH_CHECK=1 bash scripts/deploy.sh <env> deploy (die Domain zeigt da noch nicht auf die neue Installation).