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`

```dotenv
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
```bash
python build/scripts/build_windows.py --msi
```

### macOS
```bash
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
```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
```

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

```text
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:

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