webdrop-bridge/docs/CONFIGURATION_BUILD.md

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:

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

python build/scripts/build_windows.py --msi

macOS

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

python build/scripts/build_windows.py --msi --env-file path/to/customer1.env

macOS

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:

# 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

# 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

# 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.