From 8d2e60126eaaf119c24f57d2e12e7f1e3fef9757 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Kr=C3=BCger?= Date: Fri, 11 Sep 2026 23:08:10 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20Doc.md=20mit=20Projekt=C3=BCberblick=20?= =?UTF-8?q?erg=C3=A4nzen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Setup, Struktur, Kommandos und SigV4-Kram kurz dokumentiert, damit nicht jeder wieder von vorne den Code durchwühlen muss. --- Doc.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 Doc.md diff --git a/Doc.md b/Doc.md new file mode 100644 index 0000000..0ca60b1 --- /dev/null +++ b/Doc.md @@ -0,0 +1,115 @@ +# r9t Frontend + +Web-UI für unseren S3-kompatiblen Object Storage (r9t). Rein clientseitiges Nuxt/Vue-Frontend, das Buckets und Objekte auflistet, Objekte anzeigt/hochlädt/löscht und dafür Requests direkt per AWS SigV4 signiert. + +## Tech-Stack + +- [Nuxt 4](https://nuxt.com/) (Vue 3, TypeScript) +- [Tailwind CSS 4](https://tailwindcss.com/) (via `@tailwindcss/vite`) +- Kein State-Management-Framework, kein Backend-Code hier — nur UI + ein schlanker S3-Client + +## Setup + +Voraussetzung: Node.js (siehe `Dockerfile`, dort läuft `node:22.9.0-alpine`). + +```bash +npm install +``` + +`.env` aus der Vorlage anlegen: + +```bash +cp .env.example .env +``` + +Relevante Variablen (siehe `nuxt.config.ts` → `runtimeConfig.public`): + +| Variable | Zweck | Default (Beispiel) | +|-------------------------------|---------------------------------------------|---------------------| +| `NUXT_PUBLIC_S3_ACCESS_KEY` | Access Key für SigV4-Signierung der Requests | `devkey` | +| `NUXT_PUBLIC_S3_SECRET_KEY` | Secret Key für SigV4-Signierung | `devsecret` | + +Wichtig: Diese Keys landen im Public Runtime Config, sind also im Client-Bundle sichtbar. Für den Dev-Betrieb gegen einen lokalen/Test-Storage okay, für produktive Zugangsdaten nicht geeignet — das müsste über einen Backend-Proxy laufen, der Requests serverseitig signiert. + +## Entwicklung + +```bash +npm run dev +``` + +Läuft auf `http://localhost:3000`. Requests an `/api/*` werden per Vite-Dev-Proxy (siehe `nuxt.config.ts`) an `http://localhost:8080` weitergeleitet und dort landet der eigentliche S3-Server. Heißt: Für lokale Entwicklung muss der Storage-Server separat auf Port 8080 laufen. + +## Build & Produktion + +```bash +npm run build # Produktions-Build (.output/) +npm run preview # lokal den Produktions-Build testen +npm run generate # statischer Export, falls mal gebraucht +``` + +### Docker + +```bash +docker build --build-arg VERSION= -t r9t-frontend . +docker run -p 3000:3000 r9t-frontend +``` + +Das Dockerfile baut mit `npx nuxi build` und startet den Nitro-Server via `node .output/server/index.mjs`. + +### CI/CD + +`Jenkinsfile` baut das Image, pusht es nach `harbor.dinauer.dev/r9t/frontend:` und räumt danach den lokalen Build-Agent wieder auf. Kein automatischer Deploy-Schritt enthalten — Image landet nur in der Registry. + +## Projektstruktur + +``` +app/ +├── app.vue # Root-Komponente, App-Layout, State-Orchestrierung +├── assets/css/main.css # Tailwind-Einstieg +├── components/ +│ ├── BucketList.vue # Sidebar mit Bucket-Auswahl +│ ├── ObjectTable.vue # Objektliste im gewählten Bucket +│ ├── ObjectDetail.vue # Detail-/Aktions-Panel für ein Objekt +│ ├── PathBreadcrumb.vue +│ ├── SortHeader.vue +│ ├── ChunkBar.vue +│ ├── CopyField.vue +│ ├── FieldLabel.vue +│ ├── FileTypeBadge.vue +│ ├── AppToast.vue # Toast-Benachrichtigungen +│ └── popup/ +│ ├── PopupSlot.vue # Rendert die aktuell offene Popup-Instanz +│ ├── ConfirmPopup.vue +│ ├── UploadPopup.vue +│ └── TextPreviewPopup.vue +├── composables/ +│ ├── useS3Client.ts # High-Level S3-Operationen (list/get/put/delete) +│ └── usePopup.ts # Globaler Popup-Store +└── utils/ + ├── sigv4.ts # AWS SigV4 Request-Signierung (browserseitig, WebCrypto) + ├── s3xml.ts # Parsen der S3 List-XML-Responses + ├── popup.ts # Popup-Klasse/Config-Typen + └── format.ts # Formatierungs-Helper (Größen, Daten, o.ä.) +``` + +Sonstige relevante Dateien: + +- `nuxt.config.ts` — Runtime-Config, Tailwind-Plugin, Dev-Proxy nach `/api` +- `Dockerfile` — Produktions-Image +- `Jenkinsfile` — Build-Pipeline (Image bauen + nach Harbor pushen) +- `.env.example` — Vorlage für lokale Env-Variablen + +## Funktionsweise (Kurzfassung) + +1. `app.vue` lädt beim Mount die Bucket-Liste (`useS3Client().listBuckets()`). +2. Bei Bucket-Auswahl werden die Objekte geladen (`listObjects`), gefiltert per Suchfeld (Client-seitig, kein Server-Filter). +3. Jeder Request wird vorher in `sigv4.ts` per AWS4-HMAC-SHA256 signiert (Access/Secret Key aus der Runtime-Config) und läuft über den `/api`-Proxy zum eigentlichen S3-Server. +4. Objekt-Aktionen (Download, Upload, Löschen, Text-Vorschau) laufen über Popups (`usePopup`/`PopupSlot`), die dynamisch eine Vue-Komponente rendern. +5. Bucket-Erstellung ist aktuell nur gemockt (`mockAction` in `app.vue`) — das UI unterstützt bislang keinen echten Bucket-Create/Delete. + +## Bekannte Einschränkungen + +- Keine Authentifizierung im UI selbst — Access/Secret Key liegen statisch in der Config. +- Kein serverseitiger Proxy für die Signierung, SigV4 läuft komplett im Browser. +- Bucket-Erstellung ist nicht implementiert, nur ein Platzhalter-Toast. +- Kein automatisierter Test-Runner im Repo vorhanden (kein `test`-Script in `package.json`).