162 lines
4.5 KiB
Markdown
162 lines
4.5 KiB
Markdown
# 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.
|