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