diff --git a/README.md b/README.md index f948fcc..e47c838 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,166 @@ -# EnvHelper +

+

EnvHelper

+

+ Lokale Windows-App zum sauberen Ausfuellen von .env-Vorlagen. +

+

-**EnvHelper** ist eine lokale Windows-Desktop-App zum Ausfüllen von `.env` Vorlagen. Sie erkennt `CHANGE_ME` Platzhalter, erzeugt passende Werte im erwarteten Format und gibt eine fertige `.env` aus. +

+ Platform + Stack + Build + Version +

+ +--- + +## Inhalt + +- [Kurzbeschreibung](#kurzbeschreibung) +- [Features](#features) +- [Workflow](#workflow) +- [Beispiel](#beispiel) +- [Erkennung](#erkennung) +- [Standardwerte](#standardwerte) +- [Download und Artefakte](#download-und-artefakte) +- [Entwicklung](#entwicklung) +- [Windows Build](#windows-build) +- [Sicherheit](#sicherheit) +- [Projektinfos](#projektinfos) + +--- + +## Kurzbeschreibung + +EnvHelper liest `.env`-Dateien oder reinen Text ein, erkennt `CHANGE_ME`-Platzhalter und erzeugt passende Werte im erwarteten Format. Gleiche Platzhalter erhalten denselben Wert, damit zusammenhaengende Variablen wie `DATABASE_URL` und `POSTGRES_PASSWORD` synchron bleiben. + +Die App arbeitet lokal als Desktop-Tool. Es werden keine Secrets an externe Dienste gesendet. + +--- + +## Features + +| Bereich | Beschreibung | +| --- | --- | +| Datei und Text | `.env` laden, Text direkt einfuegen, Ergebnis kopieren oder speichern | +| Placeholder | Erkennt `CHANGE_ME...` Werte und ersetzt sie formatbewusst | +| Konsistenz | Gleiche Placeholder werden im gesamten Output identisch ersetzt | +| Formate | Passwoerter, Secrets, Base64, Hex, UUID, Ports, URLs, E-Mail, API-Key-Praefixe | +| Standardwerte | Erkennt naheliegende Defaults automatisch und erlaubt manuelle Overrides | +| Desktop UI | Kompakte Windows-App mit nativer Fensterleiste, Darkmode und Settings | +| Sprachen | Deutsch, Englisch, Spanisch, Franzoesisch, Niederlaendisch | +| Build | Windows Setup und Portable EXE ueber Gitea Runner | + +--- + +## Workflow ```text -Status: Desktop App -Plattform: Windows -Stack: Electron, React, Vite, TypeScript -Build: Gitea Actions Runner +1. .env Datei laden oder Text einfuegen +2. Automatische Standardwerte pruefen oder eigene Defaults ergaenzen +3. CHANGE_ME Platzhalter generieren lassen +4. Output kopieren oder als neue .env speichern ``` -## Highlights - -- `.env` Datei laden oder reinen Text einfügen -- `CHANGE_ME...` Platzhalter automatisch erkennen -- Passwörter, Secrets, Base64-Keys, UUIDs, Ports, URLs und E-Mails heuristisch erzeugen -- Gleiche Placeholder konsistent mit demselben Wert ersetzen -- Standardwerte pro Key definieren und im Output überschreiben lassen -- Hell/Dunkel/System Theme -- Einstellungen mit Sprache, Version und Projektinfos -- Ausgabe kopieren oder als neue `.env` speichern - -## Vorschau - -Screenshots können später im Repository ergänzt werden. - ```text -┌─────────────────────────────────────────────────────────────┐ -│ EnvHelper Datei laden .env speichern Theme Settings │ -├─────────────────────────────┬───────────────────────────────┤ -│ Input │ Output │ -│ DATABASE_URL=...CHANGE_ME │ DATABASE_URL=...generated... │ -├─────────────────────────────┴───────────────────────────────┤ -│ Standardwerte Erkannte Anforderungen │ -└─────────────────────────────────────────────────────────────┘ +Input Verarbeitung Output +----- ------------ ------ +DATABASE_URL=... Placeholder erkennen DATABASE_URL=... +POSTGRES_PASSWORD=... -> Format ableiten -> POSTGRES_PASSWORD=... +SESSION_SECRET=... Werte lokal erzeugen SESSION_SECRET=... ``` +--- + ## Beispiel Eingabe: ```env -DATABASE_URL=postgresql://hilden_app:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/hilden_directory +APP_PORT=3000 +NODE_ENV=production +PUBLIC_BASE_URL=CHANGE_ME_PUBLIC_URL + +DATABASE_URL=postgresql://app_user:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/app_db POSTGRES_PASSWORD=CHANGE_ME_POSTGRES_PASSWORD + SESSION_SECRET=CHANGE_ME_AT_LEAST_32_RANDOM_CHARACTERS ENCRYPTION_KEY_BASE64=CHANGE_ME_32_RANDOM_BYTES_AS_BASE64 -BOOTSTRAP_ADMIN_EMAIL=admin@example.local +BOOTSTRAP_ADMIN_EMAIL=CHANGE_ME_EMAIL +BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_LONG_INITIAL_ADMIN_PASSWORD ``` -Ausgabe: +Moeglicher Output: ```env -DATABASE_URL=postgresql://hilden_app:generated-postgres-password@postgres:5432/hilden_directory -POSTGRES_PASSWORD=generated-postgres-password -SESSION_SECRET=generated-url-safe-secret -ENCRYPTION_KEY_BASE64=generated-base64-key +APP_PORT=3000 +NODE_ENV=production +PUBLIC_BASE_URL=https://example.local + +DATABASE_URL=postgresql://app_user:K2d8rF7s...@postgres:5432/app_db +POSTGRES_PASSWORD=K2d8rF7s... + +SESSION_SECRET=n9pS...urlSafeSecret +ENCRYPTION_KEY_BASE64=4G8t...base64Value BOOTSTRAP_ADMIN_EMAIL=admin@example.local +BOOTSTRAP_ADMIN_PASSWORD=Wz4...strongPassword ``` -Die tatsächlichen Werte werden zufällig lokal erzeugt. +Die echten Werte werden zufaellig lokal erzeugt. + +--- + +## Erkennung + +EnvHelper priorisiert den Inhalt des Platzhalters vor dem umgebenden Variablennamen. Dadurch wird zum Beispiel `CHANGE_ME_POSTGRES_PASSWORD` innerhalb einer `DATABASE_URL` als Passwort erkannt und nicht faelschlich als URL. + +Unterstuetzte Muster sind unter anderem: + +| Muster | Ergebnis | +| --- | --- | +| `CHANGE_ME_POSTGRES_PASSWORD` | starkes URL-sicheres Passwort | +| `CHANGE_ME_32_RANDOM_BYTES_AS_BASE64` | 32 zufaellige Bytes als Base64 | +| `CHANGE_ME_HEX_TOKEN` | zufaellige Bytes als Hex | +| `CHANGE_ME_UUID` | UUID v4 | +| `CHANGE_ME_PUBLIC_URL` | HTTPS URL | +| `CHANGE_ME_EMAIL` | E-Mail-Adresse | +| `STRIPE_SECRET_KEY=CHANGE_ME` | Stripe-artiger `sk_test_...` Wert | +| `STRIPE_WEBHOOK_SECRET=CHANGE_ME` | Stripe-artiger `whsec_...` Wert | +| `AWS_ACCESS_KEY_ID=CHANGE_ME` | AWS/S3-artiges Access-Key-ID Format | + +Weitere Heuristiken decken typische `.env.example`-Variablen fuer SMTP, S3/MinIO, Redis, RabbitMQ, CORS, Log-Level, Environment-Flags und API Keys ab. + +--- ## Standardwerte -Standardwerte werden in einer eigenen Sektion gepflegt. Wenn ein Key dort eingetragen ist, überschreibt der Wert den entsprechenden Output-Key. +Standardwerte werden in einer eigenen Sektion angezeigt. Die App erkennt naheliegende Defaults automatisch, zum Beispiel: -Beispiel: +| Key | Default | +| --- | --- | +| `BOOTSTRAP_ADMIN_EMAIL` | `admin@example.local` | +| `NODE_ENV` | `production` | +| `LOG_LEVEL` | `info` | +| `SMTP_PORT` | `587` | +| `S3_REGION` | `eu-central-1` | +| `REDIS_URL` | `redis://redis:6379/0` | -```text -BOOTSTRAP_ADMIN_EMAIL = admin@example.local -``` +Manuelle Defaults koennen jederzeit hinzugefuegt werden. Sie ueberschreiben automatisch erkannte Defaults und wirken nur auf den Output, nicht auf die Eingabevorlage. -Dann wird im Output immer dieser Wert gesetzt, auch wenn die Vorlage bereits eine andere E-Mail enthält. - -## Sicherheit - -EnvHelper arbeitet lokal. Die Werte werden im Renderer mit Web-Crypto erzeugt und nicht an externe Dienste gesendet. Die App ist ein Helfer für Vorlagen, ersetzt aber keine zentrale Secret-Verwaltung für produktive Infrastruktur. - -### Windows Defender und SmartScreen - -Windows kann unsignierte `.exe` Dateien als unbekannten Herausgeber einstufen. Das ist kein EnvHelper-spezifischer Fehler, sondern die normale Windows-Sicherheitsprüfung für Apps ohne vertrauenswürdige Authenticode-Signatur. - -Für signierte Builds kann der Gitea Runner später diese Secrets verwenden: - -```text -WINDOWS_CSC_LINK -WINDOWS_CSC_KEY_PASSWORD -``` - -`WINDOWS_CSC_LINK` ist das Code-Signing-Zertifikat, zum Beispiel als Base64-kodierte `.pfx` Datei oder als erreichbare Zertifikats-URL. `WINDOWS_CSC_KEY_PASSWORD` ist das Passwort des Zertifikats. Ohne ein gültiges Code-Signing-Zertifikat bleibt der Herausgeber für Windows unbekannt. +--- ## Download und Artefakte -Der Windows-Build erzeugt zwei Dateien: +Der Windows-Build erzeugt zwei nutzbare Dateien: -- `EnvHelper-0.1.0-setup-x64.exe` -- `EnvHelper-0.1.0-portable-x64.exe` +```text +EnvHelper-0.1.0-setup-x64.exe +EnvHelper-0.1.0-portable-x64.exe +``` -Die Dateien werden vom Gitea Runner als Actions-Artefakt und als Generic Package veröffentlicht. +Die Dateien werden vom Gitea Runner als Actions-Artefakt und als Generic Package veroeffentlicht. + +--- ## Entwicklung @@ -104,30 +169,64 @@ npm install npm run dev ``` -In einem zweiten Terminal kann der Electron-Build geprüft werden: +Build pruefen: ```bash npm run build ``` -## Windows Build - -Der Windows-Build läuft über Gitea Actions und nutzt den Linux Runner mit Wine: +Windows-Paket lokal bauen: ```bash npm run dist:win ``` -Workflow: +--- + +## Windows Build + +Der produktive Windows-Build laeuft ueber Gitea Actions: ```text .gitea/workflows/build-windows.yml ``` -Der Runner installiert Node.js, Wine, baut die App mit Electron Builder und lädt die fertigen `.exe` Artefakte hoch. +Der Runner: + +1. checkt das Repository aus, +2. installiert Node.js, +3. installiert Wine fuer Windows-Packaging auf Linux, +4. baut Vite, TypeScript und Electron, +5. erzeugt Setup und Portable EXE, +6. laedt Artefakte und Packages nach Gitea hoch. + +--- + +## Sicherheit + +EnvHelper erzeugt Werte lokal im Renderer mit Web-Crypto. Die App ist ein Helfer fuer `.env`-Vorlagen und ersetzt keine zentrale Secret-Verwaltung fuer produktive Infrastruktur. + +### Windows Defender und SmartScreen + +Windows kann Apps mit unbekanntem Herausgeber blockieren oder verzoegert starten. Das liegt normalerweise an fehlender Reputation oder fehlendem vertrauenswuerdigem Code-Signing-Zertifikat. + +Der Workflow ist fuer Code Signing vorbereitet: + +```text +WINDOWS_CSC_LINK +WINDOWS_CSC_KEY_PASSWORD +``` + +`WINDOWS_CSC_LINK` ist das Zertifikat, zum Beispiel als Base64-kodierte `.pfx` Datei oder als erreichbare Zertifikats-URL. `WINDOWS_CSC_KEY_PASSWORD` ist das Passwort des Zertifikats. + +--- ## Projektinfos -- Autor: `MrSphay` -- Repository: `MrSphay/envHelper` -- App-ID: `de.wilkensxl.envhelper` +| Feld | Wert | +| --- | --- | +| Autor | `MrSphay` | +| Repository | `MrSphay/envHelper` | +| App-ID | `de.wilkensxl.envhelper` | +| Stack | Electron, React, Vite, TypeScript | +| README-Stil | Inspiriert von `andreasbm/readme` |