webdrop-bridge/docs/CONFIGURATION_BUILD.md

Configuration Management for Builds

This document explains how configuration and branding work for development builds, packaged installers, and installed applications.

Current Configuration Model

WebDrop Bridge now uses a JSON-first runtime configuration with optional .env bootstrap defaults:

1. Bootstrap .env (optional)

   • Loaded very early during startup
   • Useful for packaged defaults such as APP_NAME, BRAND_ID, update channel, and default web source
   • Commonly used by branded Windows/MSI and macOS/DMG builds

2. Persisted JSON config (preferred)

   • Windows: %APPDATA%\<config_dir_name>\config.json
   • macOS/Linux: ~/.config/<config_dir_name>/config.json
   • Created and maintained by the Settings dialog
   • Takes precedence for day-to-day user settings after first launch

In practice, installers can ship with a curated .env, while user changes are saved into config.json.

What Belongs Where?

Use JSON config for:

• url_mappings
• allowed_roots
• allowed_urls
• window size and logging settings
• language
• active_branding_id

Use .env bootstrap defaults for:

• APP_NAME
• BRAND_ID
• APP_CONFIG_DIR_NAME
• update channel and repository defaults
• packaged first-launch defaults for customer-specific builds

Example Bootstrap .env

APP_NAME=WebDrop Bridge
BRAND_ID=webdrop_bridge
APP_CONFIG_DIR_NAME=webdrop_bridge
WEBAPP_URL=https://example.com
ALLOWED_ROOTS=Z:/,C:/Users/Public
ALLOWED_URLS=
LANGUAGE=auto
LOG_LEVEL=INFO
ENABLE_LOGGING=true
WINDOW_WIDTH=1024
WINDOW_HEIGHT=768

Building with Default Configuration

If you want to use the project's default .env file from the repository root:

Windows

python build/scripts/build_windows.py --msi

macOS

bash build/scripts/build_macos.sh

The build scripts currently expect a .env file to exist. This is intentional so packaged builds always have explicit bootstrap defaults.

Building with Custom Customer Defaults

For customer-specific or branded releases, provide a different .env file during packaging:

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

This bundles those bootstrap defaults into the packaged app while still allowing the installed application to persist later changes in JSON.

Example: Multi-Customer Setup

webdrop_bridge/
├── .env
├── build/
│   └── scripts/
│       ├── build_windows.py
│       └── build_macos.sh
├── customer_configs/
│   ├── acme_corp.env
│   ├── globex_corporation.env
│   └── initech.env
└── config.example.json

Then build per customer or brand:

python build/scripts/build_windows.py --msi --env-file customer_configs/acme_corp.env
python build/scripts/build_windows.py --msi --env-file customer_configs/globex_corporation.env
bash build/scripts/build_macos.sh --env-file customer_configs/initech.env

What Gets Bundled into Installers?

During packaging, the supplied .env file is bundled so the application can resolve:

• app display name
• brand/config directory name
• update channel defaults
• initial web source and logging defaults

After installation, the application normally saves user-controlled settings to the JSON config file in the app data directory.

Recommended Runtime Workflow

1. Package the app with the correct .env bootstrap defaults.
2. Launch the app once.
3. Configure URLs, mappings, language, and branding in the Settings dialog.
4. Let the app save config.json in the brand-specific config directory.
5. Reuse exported profiles or branding templates for future setups.

Build Command Reference

Windows

# Default build using the repository root .env
python build/scripts/build_windows.py --msi

# Customer-specific defaults
python build/scripts/build_windows.py --msi --env-file customer_configs/acme.env

# Without MSI (just the packaged executable)
python build/scripts/build_windows.py

# Sign executable (requires signing setup)
python build/scripts/build_windows.py --msi --code-sign

macOS

# Default build using the repository root .env
bash build/scripts/build_macos.sh

# Customer-specific defaults
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

Validation Notes

The build process validates that:

1. the specified .env file exists,
2. packaging metadata can be resolved, and
3. the resulting installer assets are created successfully.

If you need the full runtime JSON schema, see CONFIG_README.md.