feat: Implement configuration bundling for customer-specific builds and enhance build scripts

2026-01-30 11:09:19 +01:00 · 2026-01-30 11:09:19 +01:00 · a355c13c82
commit a355c13c82
parent 4e5deab7e9
5 changed files with 750 additions and 22 deletions
--- a/docs/CONFIGURATION_BUILD.md
+++ b/docs/CONFIGURATION_BUILD.md
@ -0,0 +1,162 @@
+# Configuration Management for Builds
+
+This document explains how configuration is handled when building executables and installers for WebDrop Bridge.
+
+## Overview
+
+WebDrop Bridge uses `.env` files for runtime configuration. When building distributable packages (exe, MSI, or DMG), the `.env` file is **bundled into the application** so that users receive pre-configured settings.
+
+## Configuration File
+
+The configuration file must be named `.env` and contains settings like:
+
+```dotenv
+APP_NAME=WebDrop Bridge
+APP_VERSION=0.1.0
+WEBAPP_URL=https://example.com
+ALLOWED_ROOTS=Z:/,C:/Users/Public
+ALLOWED_URLS=
+LOG_LEVEL=INFO
+LOG_FILE=logs/webdrop_bridge.log
+ENABLE_LOGGING=true
+WINDOW_WIDTH=1024
+WINDOW_HEIGHT=768
+```
+
+See `.env.example` for a template with all available options.
+
+## Building with Default Configuration
+
+If you want to use the project's `.env` file (in the project root), simply run:
+
+### Windows
+```bash
+python build/scripts/build_windows.py --msi
+```
+
+### macOS
+```bash
+bash build/scripts/build_macos.sh
+```
+
+**Important:** The build will **fail** if `.env` doesn't exist. This prevents accidentally shipping without configuration.
+
+## Building with Custom Configuration
+
+For different customers or deployments, you can specify a custom `.env` file:
+
+### Windows
+```bash
+python build/scripts/build_windows.py --msi --env-file path/to/customer1.env
+```
+
+### macOS
+```bash
+bash build/scripts/build_macos.sh --env-file path/to/customer1.env
+```
+
+The custom `.env` file will be bundled into the executable and users will receive those pre-configured settings.
+
+## Example: Multi-Customer Setup
+
+If you have different customer configurations:
+
+```
+webdrop_bridge/
+├── .env                           # Default project configuration
+├── .env.example                   # Template
+├── build/
+│   └── scripts/
+│       ├── build_windows.py
+│       └── build_macos.sh
+├── customer_configs/              # Create this for customer-specific settings
+│   ├── acme_corp.env
+│   ├── globex_corporation.env
+│   └── initech.env
+└── ...
+```
+
+Then build for each customer:
+
+```bash
+# ACME Corp
+python build/scripts/build_windows.py --msi --env-file customer_configs/acme_corp.env
+
+# Globex Corporation
+python build/scripts/build_windows.py --msi --env-file customer_configs/globex_corporation.env
+
+# Initech
+python build/scripts/build_windows.py --msi --env-file customer_configs/initech.env
+```
+
+Each MSI will include that customer's specific configuration (URLs, allowed paths, etc.).
+
+## What Gets Bundled
+
+When building, the `.env` file is:
+1. ✅ Copied into the PyInstaller bundle
+2. ✅ Extracted to the application's working directory when the app starts
+3. ✅ Automatically loaded by `Config.from_env()` at startup
+
+Users **do not** need to create their own `.env` files.
+
+## After Installation
+
+When users run the installed application:
+1. The embedded `.env` is automatically available
+2. Settings are loaded and applied
+3. Users can optionally create a custom `.env` in the installation directory to override settings
+
+This allows:
+- **Pre-configured deployments** for your customers
+- **Easy customization** by users (just edit the `.env` file)
+- **No manual setup** required after installation
+
+## Build Command Reference
+
+### Windows
+```bash
+# Default (.env from project root)
+python build/scripts/build_windows.py --msi
+
+# Custom .env file
+python build/scripts/build_windows.py --msi --env-file customer_configs/acme.env
+
+# Without MSI (just EXE)
+python build/scripts/build_windows.py
+
+# Sign executable (requires CODE_SIGN_CERT env var)
+python build/scripts/build_windows.py --msi --code-sign
+```
+
+### macOS
+```bash
+# Default (.env from project root)
+bash build/scripts/build_macos.sh
+
+# Custom .env file
+bash build/scripts/build_macos.sh --env-file customer_configs/acme.env
+
+# Sign app (requires Apple developer certificate)
+bash build/scripts/build_macos.sh --sign
+
+# Notarize app (requires Apple ID)
+bash build/scripts/build_macos.sh --notarize
+```
+
+## Configuration Validation
+
+The build process validates that:
+1. ✅ The specified `.env` file exists
+2. ✅ All required environment variables are present
+3. ✅ Values are valid (LOG_LEVEL is valid, paths exist for ALLOWED_ROOTS, etc.)
+
+If validation fails, the build stops with a clear error message.
+
+## Version Management
+
+The `APP_VERSION` is read from two places (in order):
+1. `.env` file (if specified)
+2. `src/webdrop_bridge/__init__.py` (as fallback)
+
+This allows you to override the version per customer if needed.