MrSphay/envHelper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
v0.1.0
envHelper/README.md
MrSphay a35acb3ea9
All checks were successful
Build Windows App / build-windows (push) Successful in 25m17s
Details
Harden app for release readiness
2026-05-02 01:01:57 +02:00

285 lines
11 KiB
Markdown
Raw Permalink Blame History

<p align="center">
<h1 align="center">EnvHelper</h1>
<p align="center">
A local Windows desktop app for turning <code>.env</code> templates into deployable configuration files.
</p>
</p>
<p align="center">
<img alt="Platform" src="https://img.shields.io/badge/platform-Windows-2563eb">
<img alt="Stack" src="https://img.shields.io/badge/stack-Electron%20%2B%20React%20%2B%20TypeScript-0f766e">
<img alt="Build" src="https://img.shields.io/badge/build-Gitea%20Runner-a855f7">
<img alt="Version" src="https://img.shields.io/badge/version-0.1.0-111827">
</p>
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Workflow](#workflow)
- [Example](#example)
- [Placeholder Detection](#placeholder-detection)
- [Default Values](#default-values)
- [Downloads and Artifacts](#downloads-and-artifacts)
- [Development](#development)
- [Windows Build](#windows-build)
- [README Generation](#readme-generation)
- [Security](#security)
- [Project Info](#project-info)
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Overview
EnvHelper reads `.env` files or plain text, detects `CHANGE_ME` placeholders, infers the required value format, and produces a ready-to-use output file. Identical placeholders are replaced with the same generated value, so related variables such as `DATABASE_URL` and `POSTGRES_PASSWORD` stay in sync.
The app is local-first. It does not send generated secrets or input files to external services.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Features
| Area | Description |
| --- | --- |
| File and text input | Load `.env` files, paste text directly, copy output, or save a new `.env` |
| Placeholder replacement | Detects `CHANGE_ME...` values and replaces them with format-aware values |
| Consistency | Reuses the same generated value for repeated placeholders |
| Supported formats | Passwords, secrets, Base64, hex, UUIDs, ports, URLs, email addresses, and API key prefixes |
| Default values | Detects likely defaults automatically and allows manual overrides |
| Desktop UI | Compact Windows app with a native title bar, dark mode, and settings |
| Languages | German, English, Spanish, French, and Dutch |
| Build output | Windows setup and portable executables via Gitea Runner |
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Workflow
```text
1. Load a .env file or paste text.
2. Review automatically detected defaults or add your own.
3. Generate values for CHANGE_ME placeholders.
4. Copy the output or save it as a new .env file.
```
```text
Input Processing Output
----- ---------- ------
DATABASE_URL=... Detect placeholders DATABASE_URL=...
POSTGRES_PASSWORD=... -> Infer formats -> POSTGRES_PASSWORD=...
SESSION_SECRET=... Generate local values SESSION_SECRET=...
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Example
Input:
```env
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=CHANGE_ME_EMAIL
BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_LONG_INITIAL_ADMIN_PASSWORD
```
Possible output:
```env
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
```
The actual values are generated randomly on the local machine.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Placeholder Detection
EnvHelper prioritizes the placeholder text over the surrounding variable name. This prevents cases such as `CHANGE_ME_POSTGRES_PASSWORD` inside `DATABASE_URL` from being misclassified as a URL.
Supported examples:
| Pattern | Result |
| --- | --- |
| `CHANGE_ME_POSTGRES_PASSWORD` | Strong URL-safe password |
| `CHANGE_ME_32_RANDOM_BYTES_AS_BASE64` | 32 random bytes encoded as Base64 |
| `CHANGE_ME_HEX_TOKEN` | Random bytes encoded as hex |
| `CHANGE_ME_UUID` | UUID v4 |
| `CHANGE_ME_PUBLIC_URL` | HTTPS URL |
| `CHANGE_ME_EMAIL` | Email address |
| `STRIPE_SECRET_KEY=CHANGE_ME` | Stripe-like `sk_test_...` value |
| `STRIPE_WEBHOOK_SECRET=CHANGE_ME` | Stripe-like `whsec_...` value |
| `AWS_ACCESS_KEY_ID=CHANGE_ME` | AWS/S3-like access key ID format |
Additional heuristics cover common `.env.example` variables for SMTP, S3/MinIO, Redis, RabbitMQ, CORS, log levels, environment flags, and API keys.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Default Values
Default values are shown in their own section. EnvHelper detects likely defaults automatically, for example:
| 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` |
Manual defaults can always be added. They override automatically detected defaults and only affect the output, never the input template.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Downloads and Artifacts
The current Windows build can be downloaded directly from the Gitea Generic Package registry:
| Variant | Download |
| --- | --- |
| Installer | [EnvHelper-setup-x64.exe](https://git.wilkensxl.de/api/packages/MrSphay/generic/envhelper/latest/EnvHelper-setup-x64.exe) |
| Portable | [EnvHelper-portable-x64.exe](https://git.wilkensxl.de/api/packages/MrSphay/generic/envhelper/latest/EnvHelper-portable-x64.exe) |
Private package downloads may require an active Gitea session or a token with package read access.
Each build also produces versioned executable artifacts:
```text
EnvHelper-0.1.0-setup-x64.exe
EnvHelper-0.1.0-portable-x64.exe
```
The files are published by the Gitea Runner as an Actions artifact, as an immutable `version-sha` Generic Package, and as the moving `latest` Generic Package used by the links above.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Development
Install dependencies:
```bash
npm install
```
Start the Vite development server:
```bash
npm run dev
```
Check the production build:
```bash
npm run build
```
Build Windows packages:
```bash
npm run dist:win
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Windows Build
The production Windows build runs through Gitea Actions:
```text
.gitea/workflows/build-windows.yml
```
The runner:
1. checks out the repository,
2. installs Node.js,
3. installs Wine for Windows packaging on Linux,
4. builds Vite, TypeScript, and Electron,
5. creates setup and portable executables,
6. uploads artifacts and packages to Gitea.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## README Generation
The README structure follows the blueprint-based workflow from [`andreasbm/readme`](https://github.com/andreasbm/readme).
Source files:
```text
blueprint.md
blueprint.json
```
Section dividers are configured as the custom `section-line` template in `blueprint.json` and stamped from `blueprint.md`, so generated README updates keep the same rainbow separators.
Regenerate the README with:
```bash
npm run readme
```
The generated output is committed as `README.md` so Gitea can render it directly without any additional tooling.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Security
EnvHelper generates values locally in the renderer using Web Crypto. It is a helper for `.env` templates and is not a replacement for a central secret manager in production infrastructure.
Security posture:
| Area | State |
| --- | --- |
| Secret generation | Uses `crypto.getRandomValues` and `crypto.randomUUID` |
| Renderer isolation | Electron `contextIsolation` and sandbox are enabled |
| Node access | `nodeIntegration` is disabled in the renderer |
| Navigation | New windows and renderer navigation are blocked |
| Content policy | The app ships with a restrictive Content Security Policy |
| Default storage | Sensitive manual defaults such as passwords, tokens, and API keys are not persisted |
| External services | No `.env` input or generated secret is sent to external services |
### Windows Defender and SmartScreen
Windows may block or delay apps from unknown publishers. This is usually caused by missing reputation or by the absence of a trusted code-signing certificate.
The workflow is prepared for code signing:
```text
WINDOWS_CSC_LINK
WINDOWS_CSC_KEY_PASSWORD
```
`WINDOWS_CSC_LINK` is the certificate, for example a Base64-encoded `.pfx` file or a reachable certificate URL. `WINDOWS_CSC_KEY_PASSWORD` is the certificate password.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Project Info
| Field | Value |
| --- | --- |
| Author | `MrSphay` |
| Repository | `MrSphay/envHelper` |
| App ID | `de.wilkensxl.envhelper` |
| Stack | Electron, React, Vite, TypeScript |
| README workflow | Blueprint-inspired workflow based on `andreasbm/readme` |
Reference in New Issue View Git Blame Copy Permalink