From 89b35ac480a68f76a9d6f0c3e8facabc79b26ec7 Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 15 Nov 2026 08:14:57 +0100 Subject: [PATCH] =?UTF-8?q?Erg=C3=A4nze=20Deploy-Ger=C3=BCst=20und=20verwe?= =?UTF-8?q?ise=20die=20Agentenregeln=20auf=20CLAUDE.md.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- .cursor/rules/luf-betrieb.mdc | 15 ++ .dockerignore | 15 ++ .gitattributes | 9 ++ .gitea/workflows/ci-feature.yml | 28 ++++ .gitea/workflows/deploy-prod.yml | 65 ++++++++ .gitea/workflows/deploy-test.yml | 65 ++++++++ .gitignore | 18 +++ CLAUDE.md | 61 +++++++ Dockerfile | 54 +++++++ deploy/luf.env.example | 21 +++ docker-compose.yml | 122 ++++++++++++++ docker/entrypoint.sh | 17 ++ docker/nginx/default.conf | 23 +++ docker/php.ini | 7 + .../Bestandsaufnahme_Deployment_2026-11-15.md | 113 +++++++++++++ docs/betrieb/DEPLOYMENT.md | 75 +++++++++ scripts/ci-test.sh | 19 +++ scripts/deploy.sh | 153 ++++++++++++++++++ 18 files changed, 880 insertions(+) create mode 100644 .cursor/rules/luf-betrieb.mdc create mode 100644 .dockerignore create mode 100644 .gitattributes create mode 100644 .gitea/workflows/ci-feature.yml create mode 100644 .gitea/workflows/deploy-prod.yml create mode 100644 .gitea/workflows/deploy-test.yml create mode 100644 CLAUDE.md create mode 100644 Dockerfile create mode 100644 deploy/luf.env.example create mode 100644 docker-compose.yml create mode 100644 docker/entrypoint.sh create mode 100644 docker/nginx/default.conf create mode 100644 docker/php.ini create mode 100644 docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md create mode 100644 docs/betrieb/DEPLOYMENT.md create mode 100644 scripts/ci-test.sh create mode 100644 scripts/deploy.sh diff --git a/.cursor/rules/luf-betrieb.mdc b/.cursor/rules/luf-betrieb.mdc new file mode 100644 index 0000000..f59416e --- /dev/null +++ b/.cursor/rules/luf-betrieb.mdc @@ -0,0 +1,15 @@ +--- +description: Verbindliche Betriebs- und Entwicklungsregeln für Lara & Felix. Die Quelle ist CLAUDE.md. +alwaysApply: true +--- + +# Lara & Felix – Betrieb + +Lies und befolge `CLAUDE.md` im Repository-Root. Diese Regel wiederholt die dortigen Vorgaben nicht. + +- Gearbeitet wird auf `develop` oder auf `feature/*`, die nach `develop` münden. Nie auf `main` committen, pushen oder mergen. +- Ein Push auf `develop` deployt auf Test. Ein Push auf `main` deployt auf Produktion und bleibt Lars vorbehalten. +- Kein Deploy von Hand (`docker compose`, `deploy.sh`, `systemctl` auf den Servern). +- Keine Secrets ins Repo, in Commits, Logs oder Chat. +- Tests vor dem Push auf `develop`. Fehlgeschlagene Tests werden behoben, nicht umgangen. +- Medien- und Prozessgrenzen aus `CLAUDE.md` nicht aufweichen: der Web-Prozess schreibt nicht nach `originals/` und liest `derived/` und `public/` nur. diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..393917a --- /dev/null +++ b/.dockerignore @@ -0,0 +1,15 @@ +.git +.gitea +.env +.env.* +!.env.example +node_modules +vendor +storage/logs/* +storage/framework/cache/* +storage/framework/sessions/* +storage/framework/views/* +public/build +public/hot +docs +*.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6b65630 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +# Einheitliche Zeilenenden: Linux-Ziele (Docker, Runner) brauchen LF, auch wenn unter Windows eingecheckt wird. +* text=auto +*.sh text eol=lf +Dockerfile text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.conf text eol=lf +*.php text eol=lf +*.md text eol=lf diff --git a/.gitea/workflows/ci-feature.yml b/.gitea/workflows/ci-feature.yml new file mode 100644 index 0000000..bf71bc2 --- /dev/null +++ b/.gitea/workflows/ci-feature.yml @@ -0,0 +1,28 @@ +name: CI Feature + +# Tests auf Feature-Branches, ohne Deployment. Läuft auf dem llm-node-Runner (Label linux_host). +on: + push: + branches: ['feature/**'] + +jobs: + test: + runs-on: linux_host + env: + REPO_URL: http://192.168.2.144:3000/Lars/laraundfelix.git + steps: + - name: Runner prüfen + shell: bash + run: | + set -euo pipefail + [ "$(hostname)" = "llm-node" ] && [ "$(uname -m)" = "x86_64" ] || { echo "✗ Falscher Runner: $(hostname)/$(uname -m)"; exit 1; } + + - name: Commit auschecken und testen + shell: bash + run: | + set -euo pipefail + WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT + git clone --quiet "$REPO_URL" "$WORK" + cd "$WORK" + git checkout --quiet "${{ github.sha }}" + bash scripts/ci-test.sh diff --git a/.gitea/workflows/deploy-prod.yml b/.gitea/workflows/deploy-prod.yml new file mode 100644 index 0000000..5eb2f36 --- /dev/null +++ b/.gitea/workflows/deploy-prod.yml @@ -0,0 +1,65 @@ +name: Deploy Production + +# main -> Tests auf genau diesem Commit -> Build -> Deploy (Prod) -> Health, bei Fehler Rollback. +# Deploy läuft nur, wenn der Testjob grün ist. Merge auf main nur per freigegebenem Pull Request aus develop +# (Branch-Schutz in Gitea, siehe docs/betrieb/DEPLOYMENT.md). +on: + push: + branches: [main] + +jobs: + test: + runs-on: linux_host + env: + REPO_URL: http://192.168.2.144:3000/Lars/laraundfelix.git + steps: + - name: Runner prüfen + shell: bash + run: | + set -euo pipefail + [ "$(hostname)" = "llm-node" ] && [ "$(uname -m)" = "x86_64" ] || { echo "✗ Falscher Runner: $(hostname)/$(uname -m)"; exit 1; } + + - name: Commit auschecken und testen + shell: bash + run: | + set -euo pipefail + WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT + git clone --quiet "$REPO_URL" "$WORK" + cd "$WORK" + git checkout --quiet "${{ github.sha }}" + bash scripts/ci-test.sh + + deploy: + needs: test + runs-on: linux_host + env: + LUF_ENV: prod + REPO_URL: http://192.168.2.144:3000/Lars/laraundfelix.git + APP_DIR: /home/llmadmin/docker/luf-prod + ENV_FILE: /etc/luf/prod.env + COMPOSE_PROJECT: luf-prod + WEB_PORT: '3010' + steps: + - name: Runner prüfen + shell: bash + run: | + set -euo pipefail + [ "$(hostname)" = "llm-node" ] && [ "$(uname -m)" = "x86_64" ] || { echo "✗ Falscher Runner: $(hostname)/$(uname -m)"; exit 1; } + + - name: Code aktualisieren (getesteter Commit) + shell: bash + run: | + set -euo pipefail + mkdir -p "$APP_DIR" + cd "$APP_DIR" + if [ ! -d .git ]; then + git init -q + git remote add origin "$REPO_URL" + fi + git fetch origin main + git reset --hard "${{ github.sha }}" + git log -1 --oneline + + - name: Deploy + shell: bash + run: bash "$APP_DIR/scripts/deploy.sh" diff --git a/.gitea/workflows/deploy-test.yml b/.gitea/workflows/deploy-test.yml new file mode 100644 index 0000000..60b2993 --- /dev/null +++ b/.gitea/workflows/deploy-test.yml @@ -0,0 +1,65 @@ +name: Deploy Test + +# develop -> Tests -> Build -> Deploy (Test) -> Health. Deploy läuft nur, wenn die Tests grün sind. +# Aktuell auf llm-node (Runner-Label linux_host). Ein Umzug auf den Raspberry Pi braucht nur geänderte +# Werte in env: (Label runs-on, Hostname/Architektur-Guard, APP_DIR, ENV_FILE, WEB_PORT). +on: + push: + branches: [develop] + +jobs: + test: + runs-on: linux_host + env: + REPO_URL: http://192.168.2.144:3000/Lars/laraundfelix.git + steps: + - name: Runner prüfen + shell: bash + run: | + set -euo pipefail + [ "$(hostname)" = "llm-node" ] && [ "$(uname -m)" = "x86_64" ] || { echo "✗ Falscher Runner: $(hostname)/$(uname -m)"; exit 1; } + + - name: Commit auschecken und testen + shell: bash + run: | + set -euo pipefail + WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT + git clone --quiet "$REPO_URL" "$WORK" + cd "$WORK" + git checkout --quiet "${{ github.sha }}" + bash scripts/ci-test.sh + + deploy: + needs: test + runs-on: linux_host + env: + LUF_ENV: test + REPO_URL: http://192.168.2.144:3000/Lars/laraundfelix.git + APP_DIR: /home/llmadmin/docker/luf-test + ENV_FILE: /etc/luf/test.env + COMPOSE_PROJECT: luf-test + WEB_PORT: '3011' + steps: + - name: Runner prüfen + shell: bash + run: | + set -euo pipefail + [ "$(hostname)" = "llm-node" ] && [ "$(uname -m)" = "x86_64" ] || { echo "✗ Falscher Runner: $(hostname)/$(uname -m)"; exit 1; } + + - name: Code aktualisieren (getesteter Commit) + shell: bash + run: | + set -euo pipefail + mkdir -p "$APP_DIR" + cd "$APP_DIR" + if [ ! -d .git ]; then + git init -q + git remote add origin "$REPO_URL" + fi + git fetch origin develop + git reset --hard "${{ github.sha }}" + git log -1 --oneline + + - name: Deploy + shell: bash + run: bash "$APP_DIR/scripts/deploy.sh" diff --git a/.gitignore b/.gitignore index ebef3f8..5162c17 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,24 @@ node_modules/ +vendor/ .env .env.* +!.env.example dist/ +public/build/ +public/hot/ +public/storage +storage/*.key +storage/logs/ +storage/framework/cache/ +storage/framework/sessions/ +storage/framework/views/ +bootstrap/cache/*.php +.phpunit.result.cache +.phpunit.cache/ .DS_Store Thumbs.db +Homestead.json +Homestead.yaml +auth.json +composer.phar +/tmp-laravel/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ca1e528 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# Lara & Felix (LUF) – Arbeitsregeln für Claude + +Stack: Laravel 13, PHP 8.4, Filament 5, PostgreSQL, Docker Compose. Repository: Gitea `Lars/laraundfelix` (`git@192.168.2.144:Lars/laraundfelix.git`). +Dokumentation: `docs/` (Architektur, Spezifikation), Betrieb: `docs/betrieb/DEPLOYMENT.md` und `docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md`. + +## Branches und Deployment (verbindlich) + +| Branch | Zweck | Wirkung eines Pushs | +|---|---|---| +| `feature/**` | Einzelne Änderungen | Nur Tests (`ci-feature.yml`) | +| `develop` | **Arbeits- und Integrationsbranch** | Tests, dann Deploy auf **Test** (`deploy-test.yml`, Port 3011) | +| `main` | **Produktion** | Tests, dann Deploy auf **Prod** (`deploy-prod.yml`, Port 3010) | + +1. **Gearbeitet wird auf `develop` oder auf `feature/*`-Branches, die in `develop` münden.** Nie direkt auf `main`. +2. **Nie auf `main` pushen, nie nach `main` mergen und keinen Pull Request nach `main` freigeben.** Ein Push auf `main` löst sofort ein Produktiv-Deployment aus. Der Merge `develop` → `main` ist ein **manueller Schritt von Lars** (Pull Request in Gitea, nach Prüfung des Teststands). Claude bereitet höchstens vor: Zusammenfassung der Änderungen seit dem letzten Merge, Stand der Tests, offene Migrationen. +3. Nie `--force`/`--force-with-lease` auf `develop` oder `main`. Kein `git reset --hard` auf geteilten Branches. +4. Vor einem Push auf `develop` prüfen, dass die Tests lokal bzw. im Feature-Branch grün waren. Fehlgeschlagene Tests blockieren das Deployment (`needs: test`); sie nicht umgehen oder deaktivieren. +5. **Claude deployt nie von Hand.** Keine `docker compose`-, `deploy.sh`- oder `systemctl`-Aufrufe auf den Servern. Deployments entstehen ausschließlich durch die Gitea-Workflows. +6. Ein roter Workflow wird behoben, nicht überbrückt. Der Rollback im Deploy-Skript setzt nur den Code zurück, nicht die Datenbank. + +## Tests + +- **Jede Änderung am Verhalten bringt Tests mit** (Feature-Tests für Abläufe, Berechtigungen und Lizenzlogik, Unit-Tests für reine Logik). Fehler werden erst durch einen fehlschlagenden Test reproduziert, dann behoben. +- Es gibt zwei Stufen, beide als eigene Gitea-Jobs: + 1. **Gate vor dem Deploy** (`scripts/ci-test.sh`, Wegwerf-Container, Pint und `php artisan test`). Gilt für `feature/**`, `develop` und `main` und blockiert jedes Deployment. + 2. **Suite auf der Test-Instanz** (wie bei Shinkan, eigener Workflow nach dem Deploy auf `develop`): Integrations- und Browser-Tests gegen die laufende Test-Instanz (`luf-test`). Eigener Workflow, nicht Teil von `deploy-test.yml`. Wird mit U0 angelegt. +- **Tests laufen nie gegen Prod** (`luf-prod`): nicht gegen deren Datenbank, Volumes oder Medien-Mounts, nicht in deren Containern, nicht gegen deren URL. Prod prüfen allein das Gate und die Health-Checks des Deploys. (Bei Shinkan hätten Integrationstests nach einem Prod-Deploy in die Prod-Datenbank geschrieben.) +- **Auf der Test-Instanz** dürfen Tests Daten in der Test-Datenbank anlegen, aber nie die Schemas zurücksetzen: kein `RefreshDatabase`, `migrate:fresh` oder `DatabaseTruncation` gegen `luf-test`, solange die Instanz nicht ausdrücklich dafür vorgesehen ist. Laravel-Env-Werte aus dem Container (`DB_CONNECTION=pgsql`) überschreiben die SQLite-Vorgabe der `phpunit.xml`. Ein Lauf von `php artisan test` im Test-Container würde sonst die Test-Datenbank leeren. Deshalb die Instanz-Suite über HTTP (Pest-Browser/Playwright) oder in einem eigenen Container mit eigener Wegwerf-Datenbank laufen lassen. +- Tests dürfen keine Netzwerkaufrufe an echte Dienste machen (Mail, Zahlung, externe APIs). Dafür Fakes verwenden (`Mail::fake()`, `Http::fake()`, `Storage::fake()`). +- **Ein roter Test wird behoben, nicht umgangen.** Kein `skip`, `markTestSkipped`, Löschen oder Abschwächen von Assertions und kein Deaktivieren von Pint, nur um grün zu werden. Ist ein Test fachlich überholt, wird er bewusst geändert und im Commit begründet. +- Tests sind deterministisch: keine Abhängigkeit von Reihenfolge, Uhrzeit oder Zufall ohne feste Werte (`Carbon::setTestNow`, Seeds). +- **Datenbank in der Suite:** Standard ist die SQLite-In-Memory-Konfiguration aus `phpunit.xml`. Tests, die PostgreSQL-spezifisches Verhalten brauchen (JSONB, Constraints, Migrationen), laufen gegen eine eigene Wegwerf-PostgreSQL-Instanz, nicht gegen `luf-test` oder `luf-prod`. Diese Instanz ist in `scripts/ci-test.sh` noch nicht eingebaut und wird mit U0 ergänzt. +- Ein Commit auf `develop` ohne grüne Suite ist nicht zulässig. Wer die Suite nicht lokal oder auf einem Feature-Branch laufen lassen kann, sagt das, statt trotzdem auf `develop` zu pushen. + +## Migrationen + +- Migrationen müssen **abwärtskompatibel** sein (erst ergänzen, später entfernen), weil der Rollback nur den Code zurücksetzt. +- Keine Migration, die Daten löscht oder umbenennt, ohne vorherige Freigabe von Lars und ein bestätigtes Backup. + +## Server und Umgebungen + +- Test und Prod laufen vorerst **beide auf `llm-node` (192.168.2.144)**, getrennt durch Compose-Projekt (`luf-test`, `luf-prod`), Verzeichnis, Env-Datei, Volumes und Zugangsdaten. Der Raspberry Pi ist als späteres Testsystem vorgesehen (Umzug über die Variablen in `deploy-test.yml`). +- Secrets liegen nur in `/etc/luf/test.env` und `/etc/luf/prod.env` auf dem Server. **Keine Secrets, Passwörter, Keys oder `.env`-Dateien ins Repo, in Commits, Logs oder Chat-Ausgaben.** +- **Auf Servern wird nur nach ausdrücklicher Freigabe geschrieben.** Rein lesende Abfragen über vorhandene SSH-Zugänge sind erlaubt. Keine SSH-Schlüssel, Benutzer, Firewall-, Proxy- oder Runner-Änderungen. Andere Anwendungen auf den Servern (Shinkan, Gitea, mindnet, qdrant, …) dürfen nicht verändert werden. +- Ports werden nicht geraten: Vor jedem neuen Host-Port die tatsächliche Belegung prüfen (`ss`, `docker ps`). Aktuell vorgesehen: Test 3011, Prod 3010 (Stand 2026-11-15). Datenbank und PHP-FPM veröffentlichen keine Host-Ports. +- Der Reverse Proxy (Synology NAS) wird von Lars verwaltet. +- Shell-Zugriff auf llm-node: `ssh -T llmadmin@192.168.2.144 '' /media, NFS-Mount vom NAS) mit den Unterordnern +# originals/ nur queue (lesen+schreiben); der Web-Prozess (app) hat KEINEN Zugriff (Architektur 03/08) +# derived/ queue schreibt, app liest nur (private Ableitungen, Auslieferung nur über Signatur) +# public/ queue schreibt, app liest nur (bewusst öffentliche Medien) +# Pflicht in der Env-Datei: DB_DATABASE, DB_USERNAME, DB_PASSWORD (siehe deploy/luf.env.example) + +x-logging: &logging + driver: json-file + options: + max-size: "10m" + max-file: "3" + +services: + db: + image: postgres:17-alpine + restart: unless-stopped + environment: + POSTGRES_DB: ${DB_DATABASE:?DB_DATABASE fehlt} + POSTGRES_USER: ${DB_USERNAME:?DB_USERNAME fehlt} + POSTGRES_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD fehlt} + volumes: + - db-data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] + interval: 5s + timeout: 5s + retries: 20 + logging: *logging + + app: + build: + context: . + target: app + image: luf-app-${LUF_ENV:?}:${LUF_TAG:?} + restart: unless-stopped + env_file: ${LUF_ENV_FILE:?} + environment: + DB_HOST: db + DB_PORT: "5432" + volumes: + - storage-data:/var/www/html/storage + - type: bind + source: ${LUF_MEDIA_HOST:?}/derived + target: /media/derived + read_only: true + bind: + create_host_path: false + - type: bind + source: ${LUF_MEDIA_HOST:?}/public + target: /media/public + read_only: true + bind: + create_host_path: false + depends_on: + db: + condition: service_healthy + logging: *logging + + web: + build: + context: . + target: web + image: luf-web-${LUF_ENV:?}:${LUF_TAG:?} + restart: unless-stopped + ports: + - "${LUF_WEB_PORT:?}:80" + depends_on: + - app + logging: *logging + + queue: + image: luf-app-${LUF_ENV:?}:${LUF_TAG:?} + restart: unless-stopped + command: ["php", "artisan", "queue:work", "--tries=3", "--max-time=3600"] + env_file: ${LUF_ENV_FILE:?} + environment: + DB_HOST: db + DB_PORT: "5432" + volumes: + - storage-data:/var/www/html/storage + - type: bind + source: ${LUF_MEDIA_HOST:?}/originals + target: /media/originals + bind: + create_host_path: false + - type: bind + source: ${LUF_MEDIA_HOST:?}/derived + target: /media/derived + bind: + create_host_path: false + - type: bind + source: ${LUF_MEDIA_HOST:?}/public + target: /media/public + bind: + create_host_path: false + depends_on: + db: + condition: service_healthy + logging: *logging + + scheduler: + image: luf-app-${LUF_ENV:?}:${LUF_TAG:?} + restart: unless-stopped + command: ["php", "artisan", "schedule:work"] + env_file: ${LUF_ENV_FILE:?} + environment: + DB_HOST: db + DB_PORT: "5432" + volumes: + - storage-data:/var/www/html/storage + depends_on: + db: + condition: service_healthy + logging: *logging + +volumes: + db-data: + storage-data: diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100644 index 0000000..636dfd4 --- /dev/null +++ b/docker/entrypoint.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# Container-Start: Schreibrechte für storage, Laravel-Caches (nur php-fpm), dann Dienst als www-data. +set -e +cd /var/www/html + +mkdir -p storage/framework/cache/data storage/framework/sessions storage/framework/views storage/logs bootstrap/cache +chown -R www-data:www-data storage bootstrap/cache + +if [ "$1" = "php-fpm" ]; then + su-exec www-data php artisan config:cache + su-exec www-data php artisan route:cache + su-exec www-data php artisan view:cache + su-exec www-data php artisan event:cache + exec "$@" +fi + +exec su-exec www-data "$@" diff --git a/docker/nginx/default.conf b/docker/nginx/default.conf new file mode 100644 index 0000000..2a3e3f8 --- /dev/null +++ b/docker/nginx/default.conf @@ -0,0 +1,23 @@ +server { + listen 80; + server_name _; + root /var/www/html/public; + index index.php; + + client_max_body_size 64m; + + location / { + try_files $uri $uri/ /index.php?$query_string; + } + + location ~ \.php$ { + fastcgi_pass app:9000; + fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; + include fastcgi_params; + fastcgi_read_timeout 120s; + } + + location ~ /\.(?!well-known) { + deny all; + } +} diff --git a/docker/php.ini b/docker/php.ini new file mode 100644 index 0000000..17f0f4d --- /dev/null +++ b/docker/php.ini @@ -0,0 +1,7 @@ +memory_limit = 256M +upload_max_filesize = 64M +post_max_size = 64M +expose_php = Off +opcache.enable = 1 +opcache.validate_timestamps = 0 +opcache.max_accelerated_files = 20000 diff --git a/docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md b/docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md new file mode 100644 index 0000000..f45c340 --- /dev/null +++ b/docs/betrieb/Bestandsaufnahme_Deployment_2026-11-15.md @@ -0,0 +1,113 @@ +# LUF – Bestandsaufnahme Deployment und Server (Stand 2026-11-15) + +Rein lesende Untersuchung über vorhandene SSH-Zugänge. Es wurde nichts geändert, installiert oder deployt. +Kennzeichnung: **[V]** = am System verifiziert, **[D]** = nur dokumentiert (Shinkan-Repo), **[?]** = nicht verifiziert. + +## 1. SSH-Bestandsaufnahme + +| Ziel | Zugang | Ergebnis | +|---|---|---| +| Pi (`raspberrypi5`, 192.168.2.49) | Alias `pi`, User `lars`, Key `id_ed25519` | [V] Login ok. Gruppen `sudo`, `docker`, `adm`. | +| llm-node (192.168.2.144) | **Kein Alias in `~/.ssh/config`.** Adresse und User `llmadmin` stammen aus `shinkan-jinkendo/.claude/docs/technical/PROD_DEPLOYMENTS.md`, nicht geraten. | [V] Key-Login als `llmadmin` ok. Funktioniert nur mit `ssh -T … `. ARM64/AMD64 ergibt sich daraus automatisch. | [V] Workflows | +| Runner-Guard | Hostname und `uname -m` werden geprüft | [V] Workflows | +| Secrets/Env | Prod: `/etc/shinkan/prod.env` (Existenz [V], Inhalt nicht gelesen), Pflichtvariable `DB_PASSWORD`; Dev: `.env` im Deploy-Verzeichnis. Gitea-Secrets nur für E2E. | [V]/[D] | +| Migration | Beim Container-Start des Backends, Health prüft `schema_complete` | [D] | +| Health | Prod: Wiederholungen bis ca. 3 min, `/api/health/ready` mit `status/database/schema_complete`. Dev: einmalig nach `sleep 5`. | [V] Datei | +| Rollback | **Kein automatischer.** Rückfall nur manuell (Pi-Workflow per `workflow_dispatch`). Fehlschlag lässt den neuen Stand laufen. | [V] Datei | +| Backup | `RECOVERY_CONTRACT.md` im Shinkan-Repo, nicht gelesen. Medien auf NAS. | [D], nicht verifiziert | +| Proxy/TLS | siehe Abschnitt 3 | [?] | + +Hinweis: `test.yml` und `deploy-dev.yml` hängen an der festen Umgebung `shinkan-dev`. Der Runner arbeitet im Host-Modus ohne Container-Isolation. + +## 5. Übernahmeplan + +**Unverändert übernehmen** +- Gitea Actions im Host-Modus, Runner pro Host mit eindeutigem Label und Runner-Guard. +- Branch-Modell `develop`/`main`, `git reset --hard`-Deploy in ein festes Verzeichnis je Umgebung. +- Eigenes Compose-Projekt (`-p`), Konfiguration aus Env-Datei außerhalb des Repos mit Vorabprüfung (Datei lesbar, Pflichtvariablen gesetzt, keine Werte ausgeben). +- Health-Schleife mit Wiederholung und aussagekräftigem Ready-Endpunkt. + +**Anpassen** +- **Tests als Gate:** Test-Job muss vor dem Deploy laufen (`needs:`) und im Test-Workflow selbst auf einem frischen Build laufen, nicht gegen die Dev-Umgebung. Für Prod: Merge auf `main` startet erst nach grünem `develop`-Lauf. Mit Gitea umsetzbar, indem der Prod-Workflow denselben Commit zuerst testet (Tests im Workflow wiederholen) oder per Branch-Schutz mit Pflichtstatus. Entscheidung nötig. +- **Rollback:** Vor dem Deploy vorherigen Commit/Image-Tag merken. Bei rotem Health den alten Stand wiederherstellen. Shinkan hat das nicht. +- **Laravel statt FastAPI:** Health-Endpunkt (`/up` oder eigener `/health/ready` mit DB-Check) statt `/api/health/ready`. Migration als expliziter Schritt `php artisan migrate --force` vor dem Umschalten, nicht beim Container-Start. Dazu `config:cache`, `queue:restart`. +- **Ressourcen Pi:** Mit 266 MiB frei und vollem Swap ist der Pi für einen zusätzlichen Stack mit PostgreSQL grenzwertig. Build mit Composer/npm (`--no-cache`) braucht kurzfristig mehrere hundert MiB. **Risiko hoch, bevor U0 startet mit dem Besitzer klären.** +- **Betriebssystem:** Der Pi läuft Debian 12, nicht Ubuntu. Für Docker-Images ohne Folgen, in der Dokumentation korrigieren. +- **Test und Prod strikt trennen:** eigene Compose-Projekte (`luf-test`, `luf-prod`), eigene Volumes, eigene Env-Dateien (`/etc/luf/test.env` und `/etc/luf/prod.env`), eigene DB-Passwörter, eigene Medienbereiche (Prod nicht auf dem NAS-Pfad von Shinkan). +- Eigene Runner-Labels sind nicht nötig: `ubuntu-latest` (Pi) und `linux_host` (llm-node) wiederverwenden. Beide Runner bedienen dann zusätzlich LUF [V: Runner laufen]. + +## 6. U0-Implementierungsgrundlage + +Reihenfolge: +1. **Klären (blockierend):** Reverse Proxy/TLS und Domains für LUF (Test und Prod). Freigabe der Ressourcenlage auf dem Pi. Bestätigung, dass llm-node (nicht ein anderer Mini-PC) die Produktion ist. +2. Gitea-Repository `Lars/laraundfelix` [V: besteht, `main` gepusht]. Branch `develop` anlegen, Branch-Schutz auf `main`. +3. Repo-Gerüst: Laravel 13, PHP 8.4, Filament 5, `docker-compose.yml` (app/php-fpm, nginx, postgres, ohne Host-Port außer nginx), `docker-compose.test.yml`/`docker-compose.prod.yml` als Override. +4. Env-Dateien außerhalb des Repos anlegen (`/etc/luf/test.env` auf dem Pi, `/etc/luf/prod.env` auf llm-node). Das ist eine Serveränderung und braucht eine ausdrückliche Freigabe. +5. Workflow `deploy-test.yml` (push `develop`): Tests → Build → Deploy → Health, nach Shinkan-Vorbild mit Rollback. +6. Workflow `deploy-prod.yml` (push `main`, Label `linux_host`): Guard, Tests auf dem Commit, Build, Migrate, Health, Rollback. +7. Ports: Test 3095/tcp (Pi), Prod 3010/tcp (llm-node), nach erneuter Konfliktprüfung unmittelbar vor der Reservierung. + +## Nicht verifiziert +Reverse-Proxy-Konfiguration und TLS, Firewall (kein sudo), vollständige systemd-Dienste auf llm-node (Abfrage Timeout), Compose-Dateien anderer Projekte auf dem Pi (Reservierungen), Inhalt von `RECOVERY_CONTRACT.md` und tatsächliche Backup-Läufe, Ergebnisse früherer Workflow-Läufe in Gitea, Runner-Labels (nur Shinkan-Doku), Erreichbarkeit/Zugang zum NAS 192.168.2.63. diff --git a/docs/betrieb/DEPLOYMENT.md b/docs/betrieb/DEPLOYMENT.md new file mode 100644 index 0000000..c6462ab --- /dev/null +++ b/docs/betrieb/DEPLOYMENT.md @@ -0,0 +1,75 @@ +# 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: geschrieben, aber noch nicht gelaufen.** Es gibt noch keine Laravel-Anwendung im Repo (kommt mit U0), und lokal stehen weder Docker noch Composer zur Verfügung. Geprüft wurden nur Shell-Syntax und YAML. + +## 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`). +- 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 liegen die Medien unter `/media/{originals,derived,public}`. Die Laravel-Dateisysteme (`config/filesystems.php`) zeigen in U0 darauf. +- 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 fehlt:** Das Dockerfile erwartet `composer.json`, `composer.lock`, `package.json` und `npm run build` im Repo-Root, außerdem die Standardroute `/up`. +- **Zeilenenden:** `.gitattributes` erzwingt LF für Skripte, weil lokal `core.autocrlf=true` gesetzt ist. +- **Öffentliche Uploads:** Der Web-Container hat kein `storage`-Volume. Werden Dateien über `storage:link` ausgeliefert, muss das mit U0 geklärt werden. +- **Reverse Proxy:** Laravel braucht vertrauenswürdige Proxys (`X-Forwarded-Proto`), sonst stimmen `https`-URLs nicht. In U0 konfigurieren. +- **Queue:** Datenbank-Queue (`QUEUE_CONNECTION=database`), kein Redis. Reicht für den Start. +- **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. diff --git a/scripts/ci-test.sh b/scripts/ci-test.sh new file mode 100644 index 0000000..0c0d9c4 --- /dev/null +++ b/scripts/ci-test.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Qualitätsprüfung eines Commits: baut das Test-Image und führt Pint und die Testsuite im Wegwerf-Container aus. +# Greift nicht auf Test- oder Prod-Umgebung zu (eigene SQLite-In-Memory-DB, gemäß phpunit.xml). +# Aufruf im ausgecheckten Repo: bash scripts/ci-test.sh +set -euo pipefail + +SHA="$(git rev-parse --short=12 HEAD)" +IMG="luf-ci-test:$SHA" +trap 'docker rmi -f "$IMG" >/dev/null 2>&1 || true' EXIT + +echo "=== Test-Image bauen ($SHA) ===" +docker build --target test -t "$IMG" . + +echo "=== Pint und Tests ===" +docker run --rm \ + -e APP_ENV=testing \ + -e APP_KEY="base64:$(head -c 32 /dev/urandom | base64)" \ + "$IMG" +echo "✓ Qualitätsprüfung bestanden ($SHA)" diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100644 index 0000000..02875fe --- /dev/null +++ b/scripts/deploy.sh @@ -0,0 +1,153 @@ +#!/usr/bin/env bash +# LUF-Deploy. Wird vom Gitea-Workflow aufgerufen, nachdem APP_DIR auf den getesteten Commit steht. +# Ablauf: Konfiguration prüfen -> Portprüfung -> Build -> DB starten -> Migration -> Start -> Health. +# Schlägt ein Schritt fehl, wird auf den zuletzt erfolgreichen Image-Tag zurückgesetzt (Code, nicht Migrationen). +# +# Erwartete Variablen (setzt der Workflow): +# LUF_ENV test | prod +# APP_DIR Deploy-Verzeichnis (Git-Checkout) +# ENV_FILE Env-Datei außerhalb des Repos (/etc/luf/.env) +# COMPOSE_PROJECT Compose-Projektname (luf-test | luf-prod) +# WEB_PORT Host-Port des Web-Containers +set -euo pipefail + +: "${LUF_ENV:?LUF_ENV fehlt}" "${APP_DIR:?APP_DIR fehlt}" "${ENV_FILE:?ENV_FILE fehlt}" +: "${COMPOSE_PROJECT:?COMPOSE_PROJECT fehlt}" "${WEB_PORT:?WEB_PORT fehlt}" + +case "$LUF_ENV" in + test|prod) ;; + *) echo "✗ LUF_ENV=$LUF_ENV, erlaubt: test | prod"; exit 1 ;; +esac + +# Ein Deploy gleichzeitig pro Host (Build braucht RAM, Ports und Images werden gemeinsam genutzt). +exec 9>/tmp/luf-deploy.lock +flock -w 1200 9 || { echo "✗ Deploy-Sperre nach 20 min nicht erhalten"; exit 1; } + +cd "$APP_DIR" +LUF_TAG="$(git rev-parse --short=12 HEAD)" +PREV_TAG="$(cat .last_good_tag 2>/dev/null || true)" +export LUF_ENV LUF_TAG LUF_ENV_FILE="$ENV_FILE" LUF_WEB_PORT="$WEB_PORT" + +dc() { + docker compose -p "$COMPOSE_PROJECT" -f docker-compose.yml --env-file "$ENV_FILE" "$@" +} + +env_value() { + grep -E "^$1=" "$ENV_FILE" | tail -1 | cut -d= -f2- | tr -d "\"'" || true +} + +# --- 1. Konfiguration prüfen (keine Werte ausgeben) -------------------------------------------- +if [ ! -r "$ENV_FILE" ]; then + echo "✗ $ENV_FILE fehlt oder ist nicht lesbar."; exit 1 +fi +for var in APP_KEY APP_URL DB_DATABASE DB_USERNAME DB_PASSWORD; do + if [ -z "$(env_value "$var")" ]; then + echo "✗ $var ist in $ENV_FILE nicht gesetzt."; exit 1 + fi +done +app_env="$(env_value APP_ENV)" +if [ "$LUF_ENV" = prod ]; then + [ "$app_env" = production ] || { echo "✗ Prod braucht APP_ENV=production."; exit 1; } + [ "$(env_value APP_DEBUG)" = false ] || { echo "✗ Prod braucht APP_DEBUG=false."; exit 1; } +else + [ "$app_env" != production ] || { echo "✗ Test darf nicht APP_ENV=production haben."; exit 1; } +fi +echo "✓ $ENV_FILE geprüft ($LUF_ENV, Tag $LUF_TAG, vorheriger Tag ${PREV_TAG:-keiner})" + +# --- 1b. Medien-Ablage (NFS-Mount vom NAS) ----------------------------------------------------- +# Pfad ist fest an die Umgebung gebunden: Test kann nie auf den Prod-Bestand zeigen. +MEDIA_HOST="/srv/luf/$LUF_ENV/media" +media_env="$(env_value LUF_MEDIA_HOST)" +if [ -n "$media_env" ] && [ "$media_env" != "$MEDIA_HOST" ]; then + echo "✗ LUF_MEDIA_HOST in $ENV_FILE weicht von $MEDIA_HOST ab."; exit 1 +fi +export LUF_MEDIA_HOST="$MEDIA_HOST" +# Zugriff löst den automount aus; timeout, weil der Mount hart ist und bei NAS-Ausfall hängen würde. +timeout 30 ls "$MEDIA_HOST" >/dev/null 2>&1 || { echo "✗ $MEDIA_HOST nicht erreichbar (NAS/NFS-Mount prüfen)."; exit 1; } +if ! findmnt -n -t nfs4 -M "$MEDIA_HOST" >/dev/null; then + echo "✗ $MEDIA_HOST ist kein NFS-Mount. Es werden keine Medien auf die lokale Platte geschrieben."; exit 1 +fi +for d in originals derived public; do + [ -d "$MEDIA_HOST/$d" ] || timeout 30 mkdir -p "$MEDIA_HOST/$d" || { echo "✗ $MEDIA_HOST/$d fehlt und lässt sich nicht anlegen."; exit 1; } +done +echo "✓ Medien: $MEDIA_HOST (NFS), originals/derived/public vorhanden" + +# --- 2. Portkonflikt: Port darf nur von diesem Projekt belegt sein ----------------------------- +if ss -ltnH "sport = :$WEB_PORT" | grep -q .; then + if [ -z "$(dc ps -q web 2>/dev/null)" ]; then + echo "✗ Host-Port $WEB_PORT ist von einem fremden Dienst belegt. Abbruch."; exit 1 + fi +fi + +wait_for_db() { + local i status + for i in $(seq 1 40); do + status="$(docker inspect -f '{{.State.Health.Status}}' "$(dc ps -q db)" 2>/dev/null || true)" + [ "$status" = healthy ] && return 0 + sleep 3 + done + echo "✗ Datenbank nicht healthy"; return 1 +} + +wait_for_web() { + local i + for i in $(seq 1 60); do + if curl -sf -o /dev/null "http://127.0.0.1:$WEB_PORT/up"; then + echo "✓ /up antwortet (http://127.0.0.1:$WEB_PORT/up)"; return 0 + fi + sleep 3 + done + echo "✗ /up nicht erreichbar"; return 1 +} + +deploy() { + echo "=== LUF $LUF_ENV: Build $LUF_TAG ===" + dc build app web || return 1 + # Schreibprobe als www-data (echte UID im Container) auf den Medienordnern der Hintergrundverarbeitung. + dc run --rm --no-deps -T queue sh -c 'for d in originals derived public; do f=/media/$d/.write-test-$$; touch "$f" && rm "$f" || exit 1; done' || { echo "✗ Schreibprobe auf /media fehlgeschlagen (NFS-Rechte/Squash auf dem NAS prüfen)"; return 1; } + echo "✓ Schreibprobe auf /media bestanden" + dc up -d db || return 1 + wait_for_db || return 1 + echo "=== Migrationen ===" + dc run --rm --no-deps -T app php artisan migrate --force || return 1 + echo "=== Start ===" + dc up -d --remove-orphans || return 1 + wait_for_web || return 1 + # Die App muss die Datenbank wirklich erreichen, nicht nur Nginx antworten lassen. + dc exec -T app php artisan migrate:status >/dev/null || { echo "✗ App erreicht die Datenbank nicht"; return 1; } + echo "✓ App erreicht die Datenbank" +} + +rollback() { + if [ -z "$PREV_TAG" ] || [ "$PREV_TAG" = "$LUF_TAG" ]; then + echo "✗ Kein Rollback möglich (kein früherer Stand bekannt)."; return 1 + fi + for img in "luf-app-$LUF_ENV:$PREV_TAG" "luf-web-$LUF_ENV:$PREV_TAG"; do + docker image inspect "$img" >/dev/null 2>&1 || { echo "✗ Rollback-Image $img fehlt."; return 1; } + done + echo "=== Rollback auf $PREV_TAG (Datenbank-Migrationen werden nicht zurückgenommen) ===" + export LUF_TAG="$PREV_TAG" + dc up -d --no-build --remove-orphans || return 1 + wait_for_web +} + +prune_images() { + local repo + for repo in "luf-app-$LUF_ENV" "luf-web-$LUF_ENV"; do + docker image ls "$repo" --format '{{.Tag}}' \ + | grep -v -x -e "$LUF_TAG" -e "${PREV_TAG:-none}" | tail -n +3 \ + | xargs -r -I{} docker rmi "$repo:{}" >/dev/null 2>&1 || true + done +} + +if deploy; then + echo "$LUF_TAG" > .last_good_tag + prune_images + echo "=== LUF $LUF_ENV Deploy abgeschlossen ($LUF_TAG) ===" +else + echo "✗ Deploy fehlgeschlagen. Zustand:" + dc ps || true + dc logs --tail 80 app web || true + rollback || true + exit 1 +fi