Files
fewo-stommer/docs/DEPLOYMENT.md
T

93 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Deployment auf Strato
Stand: 22.10.2026 · Skript: `scripts/deploy.sh` · CI: `.gitea/workflows/deploy.yml`
## 1. Prinzip
```
Gitea (main/Tag) ──► Build (CI oder lokal): git-Stand · composer --no-dev · npm run build
│ 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.
## 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:
```bash
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
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
- Workflow `.gitea/workflows/deploy.yml`: **Tests bei jedem Push**; **Deployment** bei Tags `v*` (z. B. `git tag v1.0.0 && git push --tags`) oder per Knopfdruck (Actions › Deploy › Run workflow, Ziel production/staging).
- Voraussetzung: Gitea Actions aktiviert und ein **act_runner** registriert – passt gut auf den privaten Server (Docker). Anleitung: Gitea-Doku „Act Runner“.
- Repository-Secrets: `DEPLOY_SSH_KEY` (privater Schlüssel, dessen öffentlicher Teil bei Strato hinterlegt ist), `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_PATH`, `DEPLOY_PHP`, `DEPLOY_URL`.
## 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).