Files
laraundfelix/docs/betrieb/DEPLOYMENT.md
T
LarsandCursor 57802dfe48
Deploy Test / test (push) Successful in 18s
Deploy Test / deploy (push) Successful in 22s
Leite Programmvorschauen ueber die Queue ab und seede den Testbestand nicht erneut
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-16 10:01:13 +01:00

77 lines
7.4 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.
# LUF – Deployment (Stand 2026-11-15)
Abgeleitet aus dem Shinkan-Verfahren, siehe [Bestandsaufnahme_Deployment_2026-11-15.md](Bestandsaufnahme_Deployment_2026-11-15.md).
**Status: Anwendung U0 liegt im Repo. Ein Deploy ist erst gelaufen, wenn ein Push auf `develop` den Workflow grün durchlaufen hat.** Lokal gibt es PHP 8.4 und Node. Docker liegt auf dem Runner, nicht auf dem Entwicklungsrechner.
## Ablauf
| Auslöser | Workflow | Schritte |
|---|---|---|
| Push auf `feature/**` | `ci-feature.yml` | Commit klonen, Test-Image bauen, Pint und `php artisan test` im Wegwerf-Container |
| Push auf `develop` | `deploy-test.yml` | Tests, dann Deploy Test (`luf-test`, Port 3011) |
| Push auf `main` | `deploy-prod.yml` | Tests auf genau diesem Commit, dann Deploy Prod (`luf-prod`, Port 3010) |
- Der Deploy-Job hat `needs: test`. Sind die Tests rot, läuft kein Deploy.
- Deployt wird der getestete Commit (`github.sha`), nicht der jeweils neueste Stand des Branches.
- `scripts/deploy.sh`: Konfigurationsprüfung, Portkonflikt-Prüfung, Build, DB starten, `migrate --force`, Start, Health (`/up` und Datenbankzugriff). Bei Fehler Rollback auf den letzten erfolgreichen Image-Tag (`.last_good_tag`). Der Deploy legt keinen Demokatalog an. `DemoCatalogSeeder` bleibt für die Testsuite; der Bestand der Testinstanz wird in der Verwaltung gepflegt.
- Ein Deploy gleichzeitig pro Host (`flock`), alte Images werden bis auf die letzten Tags entfernt.
- **Rollback betrifft nur den Code.** Migrationen werden nicht zurückgenommen. Migrationen müssen daher abwärtskompatibel sein (erst ergänzen, später entfernen).
## Trennung Test und Prod (beide auf llm-node)
| | Test | Prod |
|---|---|---|
| Branch | `develop` | `main` |
| Compose-Projekt | `luf-test` | `luf-prod` |
| Deploy-Verzeichnis | `/home/llmadmin/docker/luf-test` | `/home/llmadmin/docker/luf-prod` |
| Env-Datei | `/etc/luf/test.env` | `/etc/luf/prod.env` |
| Web-Port | 3011/tcp | 3010/tcp |
| Volumes, Netz, DB | eigene (Projekt-Präfix) | eigene (Projekt-Präfix) |
Ports aus der Momentaufnahme vom 2026-11-15 (frei laut `ss` und `docker ps`). Das Skript bricht ab, wenn der Port von einem fremden Dienst belegt ist. DB, PHP-FPM, Queue und Scheduler veröffentlichen keine Host-Ports.
## Medien-Ablage auf dem NAS
| | Test | Prod |
|---|---|---|
| NAS-Ordner [?] | `/volume1/luf_media_dev` | `/volume1/luf_media` |
| Mountpunkt auf llm-node | `/srv/luf/test/media` | `/srv/luf/prod/media` |
Der Pfad auf dem NAS ist aus den Ordnernamen abgeleitet und **nicht verifiziert**: Beide Ordner standen am 2026-11-15 nicht in der NFS-Exportliste des NAS (`showmount -e`).
Aufbau je Umgebung, nach `03_Zielarchitektur.md` (Zeilen 241/242) und `08_Medien_Streaming_Kennzeichnung.md` (Abschnitt 1):
| Ordner | `queue` (Hintergrundverarbeitung) | `app` (Web-Prozess) |
|---|---|---|
| `originals/` | lesen und schreiben | **kein Zugriff** (nicht gemountet) |
| `derived/` (privat) | lesen und schreiben | nur lesen |
| `public/` | lesen und schreiben | nur lesen |
- Die Trennung geschieht über getrennte Bind-Mounts im Compose. Das NAS selbst unterscheidet nicht zwischen den Containern.
- Bind-Mounts mit `create_host_path: false`: Fehlt der NFS-Mount, startet der Container nicht, statt Medien auf die lokale Platte zu schreiben (wie bei Shinkan).
- Der Host-Pfad ist in `scripts/deploy.sh` fest an die Umgebung gebunden (`/srv/luf/$LUF_ENV/media`). Test kann nicht auf den Prod-Bestand zeigen. Das Skript prüft vor dem Build, dass der Pfad ein NFS-Mount ist, legt fehlende Unterordner an und macht nach dem Build eine Schreibprobe als `www-data`.
- Im Container ist der Pfad derselbe wie auf dem Host. Compose hängt die Unterordner an genau diese Stelle und setzt `MEDIA_PUBLIC_PATH`, `MEDIA_DERIVED_PATH` und `MEDIA_ORIGINALS_PATH` darauf. Ein abweichender Wert in der Env-Datei wird damit überstimmt.
- Die CI-Tests mounten keine Medien (`Storage::fake()`).
- Datensicherung: Originale sind laut `11_Betrieb_Sicherheit_Datenschutz.md` kritisch (NAS und außer Haus). Snapshots und Replikation für `luf_media` sind Sache des NAS und noch nicht eingerichtet.
## Einmalig auf llm-node vorzubereiten (nicht automatisiert, braucht `sudo`)
1. `sudo mkdir -p /etc/luf && sudo chown llmadmin:llmadmin /etc/luf && sudo chmod 750 /etc/luf`
2. `/etc/luf/test.env` und `/etc/luf/prod.env` aus [deploy/luf.env.example](../../deploy/luf.env.example) anlegen, `chmod 640`. Je eigener `APP_KEY` (`php artisan key:generate --show`) und eigenes DB-Passwort. Prod: `APP_ENV=production`, `APP_DEBUG=false`.
3. Auf dem Synology zwei Proxy-Einträge: Prod nach `192.168.2.144:3010`, Test nach `192.168.2.144:3011`.
4. In Gitea: Branch-Schutz für `main` (nur Pull Request, Freigabe nötig) und `develop`. Repository-Sichtbarkeit prüfen (siehe unten).
5. Backup (`borgmatic`) wieder grün, bevor produktiv deployt wird.
## Annahmen und offene Punkte
- **Repository-Zugriff der Runner [?]:** Die Workflows klonen `http://192.168.2.144:3000/Lars/laraundfelix.git` ohne Zugangsdaten, wie Shinkan. Ist das Repository privat und der Runner nicht angemeldet, schlägt der Clone fehl.
- **Gitea-Actions-Syntax [?]:** `needs:` und `github.sha` sind Standard, wurden aber auf dieser Gitea-Version nicht ausprobiert. `actions/checkout` wird bewusst nicht benutzt.
- **Laravel-Gerüst:** `composer.json`, `composer.lock`, `package.json` und `package-lock.json` liegen im Root. Die Health-Route ist `/up`. Das Image veröffentlicht die Filament-Assets beim Bau (`php artisan filament:assets`) und baut das Frontend mit `npm run build`.
- **Zeilenenden:** `.gitattributes` erzwingt LF für Skripte, weil lokal `core.autocrlf=true` gesetzt ist.
- **Öffentliche CMS-Bilder:** Der Web-Prozess schreibt nicht nach `public/`. Ein Upload liegt zuerst auf dem beschreibbaren Storage-Volume (`cms_incoming`). Die Queue kopiert nach `public/` auf dem Medienpfad. Ausgeliefert wird die Datei über die Anwendung unter `/medien/…`, zuerst aus dem öffentlichen Medienpfad, ersatzweise aus dem Eingang. `storage:link` wird dafür nicht gebraucht.
- **Reverse Proxy:** Die Anwendung vertraut weitergeleiteten Proxy-Kopfzeilen. Nginx reicht `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Port` und `X-Forwarded-For` an PHP weiter. Der Proxy vor dem Container muss `X-Forwarded-Proto` setzen, damit Adressen `https` bleiben.
- **Upload:** Filme bis 2 GB. Dieselbe Grenze gilt in Livewire (Zwischendatei, sonst 12 MB), im Formular, in PHP (`upload_max_filesize`, `post_max_size`) und in Nginx (`client_max_body_size`). Die signierte Upload-Adresse gilt 60 Minuten. Die Queue kopiert die Datei als Strom nach `derived/` und behält den Auftrag bis zu einer Stunde; `retry_after` der Datenbank-Queue liegt darüber.
- **Queue:** Datenbank-Queue (`QUEUE_CONNECTION=database`), kein Redis. Reicht für den Start. Der Worker erlaubt einem Auftrag bis zu einer Stunde (`--timeout=3600`). Das App-Image enthält `ffmpeg`. Die Queue leitet daraus Vorschaubilder und, wenn die Datei lesbar ist, drei HLS-Qualitätsstufen nach `derived/` ab. Fehlt die Ableitung, bleibt die gespeicherte Datei über den bisherigen berechtigten Abruf lesbar. Der Web-Prozess schreibt diese Ableitungen nicht.
- **Gate vor Prod:** Merge-Schutz ist eine Gitea-Einstellung und gehört nicht in die Workflows.
- **Umzug Test auf den Pi:** Werte oben in `deploy-test.yml` ändern (Label `ubuntu-latest`, Guard auf `raspberrypi5`/`aarch64`, Pfade, Port). Das Dockerfile baut auch für ARM64. Vorher Speicherlage auf dem Pi klären.