diff --git a/CHANGELOG.md b/CHANGELOG.md index 9735517..e29cab5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,9 @@ All notable changes to this project will be documented in this file. ### Changed - Improved release publishing so release descriptions can be generated from the changelog. - Updated the release workflow to use a clearer, user-facing summary for update information. -- Added "in App" Branding Management instead of using separated Brand Builds. +- Added "in App" Branding Management instead of using separated Brand Builds. ### Fixed - Removed the generic placeholder release description from published releases. - Added a reliable fallback message when no detailed notes are available. -- Instead of using "Profiles" and "Configurations" use "Setups" for more clarity. +- instead of using "Profiles" and "Configurations" use setups for more clarity. diff --git a/CONFIG_README.md b/CONFIG_README.md index 6572acd..d830dbd 100644 --- a/CONFIG_README.md +++ b/CONFIG_README.md @@ -36,10 +36,7 @@ Create a `config.json` file with the following structure: "log_file": "logs/webdrop_bridge.log", "window_width": 1024, "window_height": 768, - "enable_logging": true, - "language": "auto", - "active_branding_id": "default", - "brand_id": "agravity" + "enable_logging": true } ``` @@ -102,19 +99,6 @@ Z:\aN5PysnXIuRECzcRbvHkjL7g0\Hintergrund_Agravity.png - **`window_width`**, **`window_height`** (number): Initial window size in pixels - Default: `1024` x `768` -### Language and Branding Settings - -- **`language`** (string): UI language code - - Use `"auto"` to follow the system locale automatically - - Bundled translations currently include `en`, `de`, `fr`, `it`, `ru`, and `zh` - -- **`active_branding_id`** (string): Runtime branding template selected in the Settings dialog - - Default: `"default"` - - Useful when switching between saved branding templates without rebuilding the app - -- **`brand_id`** (string): Stable packaging/update identifier for branded variants - - Usually injected during packaging and normally left unchanged by end users - - **`log_level`** (string): Logging verbosity - Options: `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`, `"CRITICAL"` - Default: `"INFO"` @@ -165,14 +149,6 @@ You can configure multiple Azure storage accounts: } ``` -## Configuration Priority - -At startup, WebDrop Bridge first loads any bootstrap `.env` defaults and then prefers the persisted JSON config if it exists. This means: - -1. packaged or development defaults can still come from `.env`, -2. the Settings dialog saves the active runtime configuration to JSON, and -3. the JSON file becomes the main configuration source after first save. - ## Environment Variable Fallback If no JSON config exists, WebDrop Bridge will load from `.env`: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57dedbf..8112350 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Please be respectful and constructive in all interactions. We're building a welc ## Getting Started ### Prerequisites -- Python 3.9+ +- Python 3.10+ - Git - Familiarity with Qt/PySide6 or willingness to learn diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md index 3e025ce..e5460e6 100644 --- a/DEVELOPMENT_PLAN.md +++ b/DEVELOPMENT_PLAN.md @@ -1051,7 +1051,7 @@ Help Menu **Core:** - PySide6 6.6.0+ -- Python 3.9+ +- Python 3.10+ **Optional:** - PyInstaller (building) diff --git a/QUICKSTART.md b/QUICKSTART.md index 32b4f7e..5c9611e 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -143,19 +143,19 @@ brew upgrade webdrop-bridge brew uninstall webdrop-bridge ``` -For more package manager details and internal hosting options, see [docs/PACKAGE_MANAGER_SUPPORT.md](docs/PACKAGE_MANAGER_SUPPORT.md) +For more package manager details and internal hosting options, see [docs/PACKAGE_MANAGER_SUPPORT.md](../docs/PACKAGE_MANAGER_SUPPORT.md) #### Simplest: Direct wget (if you know the version) ```bash -# Replace X.Y.Z with a release version (e.g., 0.9.1) -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-win-x64.msi +# Replace VERSION with release tag (e.g., v0.8.0) +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSION/WebDropBridge_Setup.msi -# Real example - download v0.9.1 MSI -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi +# Real example - download v0.8.0 MSI +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi -# macOS - download v0.9.1 DMG -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-macos-universal.dmg +# macOS - download v0.8.0 DMG +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg ``` #### Windows (PowerShell) - Full Control Script @@ -168,7 +168,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1 .\build\scripts\download_release.ps1 -OutputDir "C:\Installers" # Download specific version -.\build\scripts\download_release.ps1 -Version "0.9.1" +.\build\scripts\download_release.ps1 -Version "0.8.0" # Skip checksum verification .\build\scripts\download_release.ps1 -Verify $false @@ -186,7 +186,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1 ./build/scripts/download_release.sh latest ~/Downloads # Download specific version -./build/scripts/download_release.sh 0.9.1 +./build/scripts/download_release.sh 0.8.0 # Skip checksum verification ./build/scripts/download_release.sh latest --no-verify diff --git a/README.md b/README.md index 21eb28f..976485f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.) -![Status](https://img.shields.io/badge/Status-Phase%205%20RC%20In%20Progress-green) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.9%2B-blue) +![Status](https://img.shields.io/badge/Status-Phase%204%20Complete-green) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue) ## Overview @@ -19,25 +19,23 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a ## Features -- ✅ **Qt-based Architecture** - Professional cross-platform desktop app via PySide6 for Windows and macOS +- ✅ **Qt-based Architecture** - Professional Windows support via PySide6 (macOS support planned) - ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations - ✅ **Drag Interception** - Converts text paths to native file operations - ✅ **Path Whitelist** - Security-conscious file system access control -- ✅ **Configuration Management** - JSON config, profile import/export, and validation -- ✅ **Runtime Branding** - Switch branding templates and packaged variants without code changes -- ✅ **Multilingual UI** - Built-in translations for English, German, French, Italian, Russian, and Chinese -- ✅ **Settings Dialog** - Language, branding, web source, path, URL, logging, and window configuration +- ✅ **Configuration Management** - Profile-based settings with validation +- ✅ **Settings Dialog** - Professional UI for path, URL, logging, and window configuration - ✅ **Auto-Update System** - Automatic release detection via Forgejo API - ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS -- ✅ **Comprehensive Testing** - Unit and integration coverage across core modules -- ✅ **Continuous Testing** - Automated CI validation +- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests (80%+ coverage) +- ✅ **Continuous Testing** - GitHub Actions test automation - ✅ **Structured Logging** - File-based logging with configurable levels ## Quick Start ### Requirements -- Python 3.9+ -- Windows 10/11 or macOS 12+ +- Python 3.10+ +- Windows 10/11 - 200 MB disk space (includes Chromium from PyInstaller) ### Installation from Pre-Built Release (Recommended) @@ -60,11 +58,11 @@ brew upgrade webdrop-bridge # Update to latest version **Option 2: Direct wget (if you know the version)** ```bash -# Replace X.Y.Z with a release version (e.g., 0.9.1) -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-win-x64.msi +# Replace VERSION with release tag (e.g., v0.8.0) +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSION/WebDropBridge_Setup.msi -# Example for v0.9.1: -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi +# Example for v0.8.0: +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi ``` **Option 3: Automated script (auto-detects platform)** @@ -95,7 +93,6 @@ python -m venv venv # Install dependencies pip install -r requirements.txt -pip install -e . # Run application python -m webdrop_bridge.main @@ -106,7 +103,6 @@ python -m webdrop_bridge.main ```bash # Install development dependencies pip install -r requirements-dev.txt -pip install -e . # Run tests pytest tests -v @@ -182,36 +178,42 @@ webdrop-bridge/ ## Configuration -WebDrop Bridge supports persisted JSON configuration plus optional bootstrap environment defaults. +WebDrop Bridge supports two configuration methods: -### 1. Settings Dialog / JSON Config (Recommended) +### 1. Settings Dialog (Recommended) Launch the application and access the Settings menu to configure: -- **General Tab** - Select the UI language or follow the system locale automatically -- **Branding Tab** - Switch, import, export, and preview runtime branding templates -- **Web Source Tab** - Configure the embedded web application URL -- **Paths / URLs / Logging / Window Tabs** - Control filesystem access, allowed sites, log output, and initial window size -- **Profiles Tab** - Save, load, import, and export complete configuration profiles +- **Paths Tab** - Add/remove allowed root directories +- **URLs Tab** - Configure allowed web URLs (whitelist mode) +- **Logging Tab** - Set log level and file location +- **Window Tab** - Configure window dimensions +- **Profiles Tab** - Save/load/export-import configuration profiles -Saved settings are written to the brand-specific application config directory as `config.json`. +Profiles are saved in `~/.webdrop_bridge/profiles/` -### 2. Bootstrap Environment Variables (`.env`) -A `.env` file is still supported for local development and branded packaged defaults. It is used when no JSON config exists yet. +### 2. Environment Variables +Create a `.env` file in the project root. Available settings: ```bash +# Application APP_NAME=WebDrop Bridge -BRAND_ID=webdrop_bridge -WEBAPP_URL=https://dev.agravity.io/ +APP_VERSION=1.0.0 + +# Paths (comma-separated) ALLOWED_ROOTS=Z:/,C:/Users/Public + +# Web URLs (empty = no restriction, items = kiosk mode) ALLOWED_URLS= -LANGUAGE=auto -LOG_LEVEL=INFO + +# Interface +WEBAPP_URL=file:///./webapp/index.html WINDOW_WIDTH=1024 WINDOW_HEIGHT=768 + +# Logging +LOG_LEVEL=INFO ENABLE_LOGGING=true ``` -For the full JSON structure and branding workflow, see [CONFIG_README.md](CONFIG_README.md) and [BRANDING_AND_RELEASES.md](docs/BRANDING_AND_RELEASES.md). - ## Testing WebDrop Bridge includes comprehensive test coverage with unit, integration, and end-to-end tests. @@ -270,20 +272,11 @@ python build/scripts/build_windows.py --msi --code-sign ``` Output: -- Portable executable: `build/dist/windows/webdrop_bridge/WebDropBridge/WebDropBridge.exe` -- Professional MSI installer: `build/dist/windows/webdrop_bridge/WebDropBridge--win-x64.msi` -- SHA256 checksum: `build/dist/windows/webdrop_bridge/WebDropBridge--win-x64.msi.sha256` +- Portable executable: `build/dist/windows/WebDropBridge/WebDropBridge.exe` (~195 MB) +- Professional MSI installer: `build/dist/windows/WebDropBridge-{version}-Setup.msi` +- SHA256 checksum: `build/dist/windows/WebDropBridge/WebDropBridge.exe.sha256` -### macOS DMG Installer - -```bash -bash build/scripts/build_macos.sh -``` - -Output: -- Application bundle: `build/dist/macos/webdrop_bridge/WebDropBridge.app` -- DMG installer: `build/dist/macos/webdrop_bridge/WebDropBridge--macos-universal.dmg` -- SHA256 checksum: `build/dist/macos/webdrop_bridge/WebDropBridge--macos-universal.dmg.sha256` +**Note on macOS**: Build scripts exist for macOS (DMG generation), but have never been built or tested. macOS support is theoretical at this point. The Qt/PySide6 architecture should support macOS, but platform-specific testing and validation would be required. ### Creating Releases @@ -321,8 +314,8 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1 ## Troubleshooting ### Application won't start -- Ensure Python 3.9+ is installed -- Check the application log in your platform-specific app data directory +- Ensure Python 3.10+ is installed +- Check `logs/webdrop_bridge.log` for errors - Verify all dependencies: `pip list` ### Drag-and-drop not working @@ -339,10 +332,10 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1 | Platform | Version | Status | Notes | |----------|---------|--------|-------| -| Windows | 10, 11 | ✅ Full | Primary target with MSI packaging and update support | -| macOS | 12, 13, 14 | ✅ Supported | Universal DMG builds for Intel and Apple Silicon | +| Windows | 10, 11 | ✅ Full | Tested on x64, MSI installer support | +| macOS | 12+ | ⚠️ **Untested** | Possible via Qt/PySide6, but never built or tested. Theoretical support only. | -**Note**: Release candidates currently target both Windows and macOS. For branded production releases, validate signing assets and installer behavior on the target platform before shipping. +**Note**: WebDrop Bridge is currently developed and tested exclusively on Windows. While the Qt/PySide6 framework supports macOS, we cannot guarantee functionality without actual macOS testing and validation. Contributions for macOS support validation are welcome. ## Contributing @@ -374,4 +367,4 @@ MIT License - see [LICENSE](LICENSE) file for details --- -**Development Phase**: Phase 5 Release Candidates | **Last Updated**: April 16, 2026 | **Current Version**: 0.9.1 | **Python**: 3.9+ | **Qt**: PySide6 (Qt 6) +**Development Phase**: Phase 4 Complete | **Last Updated**: February 18, 2026 | **Current Version**: 1.0.0 | **Python**: 3.10+ | **Qt**: PySide6 (Qt 6) diff --git a/build/package-managers/README.md b/build/package-managers/README.md index 62e5572..7f0a400 100644 --- a/build/package-managers/README.md +++ b/build/package-managers/README.md @@ -27,7 +27,7 @@ build/ 2. **Get SHA256 checksum**: ```powershell - certutil -hashfile build/dist/windows/webdrop_bridge/WebDropBridge--win-x64.msi SHA256 + certutil -hashfile build/dist/windows/WebDropBridge_Setup.msi SHA256 ``` 3. **Update package files**: @@ -42,7 +42,7 @@ build/ 5. **Publish** (requires Chocolatey API key): ```powershell - choco push webdrop-bridge..nupkg --api-key YOUR_KEY + choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY ``` ### Homebrew Formula (macOS) @@ -54,7 +54,7 @@ build/ 2. **Get SHA256 checksum**: ```bash - shasum -a 256 build/dist/macos/webdrop_bridge/WebDropBridge--macos-universal.dmg + shasum -a 256 build/dist/macos/WebDropBridge_Setup.dmg ``` 3. **Update formula**: diff --git a/build/scripts/README.md b/build/scripts/README.md index 51cac7c..c4fba4c 100644 --- a/build/scripts/README.md +++ b/build/scripts/README.md @@ -75,8 +75,8 @@ The `download_release.ps1` (Windows) and `download_release.sh` (macOS/Linux) scr ```bash # Download directly by version tag -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-win-x64.msi -wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.9.1/WebDropBridge-0.9.1-macos-universal.dmg +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi +wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg ``` **If you need to auto-detect latest (with grep/cut, no jq needed)** @@ -111,7 +111,7 @@ sha256sum -c installer.sha256 .\download_release.ps1 # Specific version to Downloads folder -.\download_release.ps1 -Version "0.9.1" -OutputDir "$env:USERPROFILE\Downloads" +.\download_release.ps1 -Version "0.8.0" -OutputDir "$env:USERPROFILE\Downloads" # Skip checksum verification .\download_release.ps1 -Verify $false @@ -124,7 +124,7 @@ sha256sum -c installer.sha256 ./build/scripts/download_release.sh # Specific version to Downloads -./build/scripts/download_release.sh 0.9.1 ~/Downloads +./build/scripts/download_release.sh 0.8.0 ~/Downloads # Skip checksum verification ./build/scripts/download_release.sh latest --no-verify @@ -165,7 +165,7 @@ Automated release creation with versioning and asset uploads. Manages consistent versioning across the project. ```bash -python build/scripts/sync_version.py --version 0.9.1 +python build/scripts/sync_version.py --version 0.8.0 ``` ## Integration Flow diff --git a/docs/CONFIGURATION_BUILD.md b/docs/CONFIGURATION_BUILD.md index dedb0af..d69abfa 100644 --- a/docs/CONFIGURATION_BUILD.md +++ b/docs/CONFIGURATION_BUILD.md @@ -1,60 +1,33 @@ # Configuration Management for Builds -This document explains how configuration and branding work for development builds, packaged installers, and installed applications. +This document explains how configuration is handled when building executables and installers for WebDrop Bridge. -## Current Configuration Model +## Overview -WebDrop Bridge now uses a **JSON-first runtime configuration** with optional `.env` bootstrap defaults: +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. -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 +## Configuration File -2. **Persisted JSON config** (preferred) - - Windows: `%APPDATA%\\config.json` - - macOS/Linux: `~/.config//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` +The configuration file must be named `.env` and contains settings like: ```dotenv APP_NAME=WebDrop Bridge -BRAND_ID=webdrop_bridge -APP_CONFIG_DIR_NAME=webdrop_bridge +APP_VERSION=0.7.1 WEBAPP_URL=https://example.com ALLOWED_ROOTS=Z:/,C:/Users/Public ALLOWED_URLS= -LANGUAGE=auto 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 default `.env` file from the repository root: +If you want to use the project's `.env` file (in the project root), simply run: ### Windows ```bash @@ -66,11 +39,11 @@ python build/scripts/build_windows.py --msi 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. +**Important:** The build will **fail** if `.env` doesn't exist. This prevents accidentally shipping without configuration. -## Building with Custom Customer Defaults +## Building with Custom Configuration -For customer-specific or branded releases, provide a different `.env` file during packaging: +For different customers or deployments, you can specify a custom `.env` file: ### Windows ```bash @@ -82,73 +55,86 @@ python build/scripts/build_windows.py --msi --env-file path/to/customer1.env 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. +The custom `.env` file will be bundled into the executable and users will receive those pre-configured settings. ## Example: Multi-Customer Setup -```text +If you have different customer configurations: + +``` webdrop_bridge/ -├── .env +├── .env # Default project configuration +├── .env.example # Template ├── build/ │ └── scripts/ │ ├── build_windows.py │ └── build_macos.sh -├── customer_configs/ +├── customer_configs/ # Create this for customer-specific settings │ ├── acme_corp.env │ ├── globex_corporation.env │ └── initech.env -└── config.example.json +└── ... ``` -Then build per customer or brand: +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 -bash build/scripts/build_macos.sh --env-file customer_configs/initech.env + +# Initech +python build/scripts/build_windows.py --msi --env-file customer_configs/initech.env ``` -## What Gets Bundled into Installers? +Each MSI will include that customer's specific configuration (URLs, allowed paths, etc.). -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 +## What Gets Bundled -After installation, the application normally saves user-controlled settings to the JSON config file in the app data directory. +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 -## Recommended Runtime Workflow +Users **do not** need to create their own `.env` files. -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. +## 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 build using the repository root .env +# Default (.env from project root) python build/scripts/build_windows.py --msi -# Customer-specific defaults +# Custom .env file python build/scripts/build_windows.py --msi --env-file customer_configs/acme.env -# Without MSI (just the packaged executable) +# Without MSI (just EXE) python build/scripts/build_windows.py -# Sign executable (requires signing setup) +# Sign executable (requires CODE_SIGN_CERT env var) python build/scripts/build_windows.py --msi --code-sign ``` ### macOS ```bash -# Default build using the repository root .env +# Default (.env from project root) bash build/scripts/build_macos.sh -# Customer-specific defaults +# Custom .env file bash build/scripts/build_macos.sh --env-file customer_configs/acme.env # Sign app (requires Apple developer certificate) @@ -158,11 +144,19 @@ bash build/scripts/build_macos.sh --sign bash build/scripts/build_macos.sh --notarize ``` -## Validation Notes +## Configuration Validation 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. +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 you need the full runtime JSON schema, see `CONFIG_README.md`. +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. diff --git a/docs/CUSTOMER_BUILD_EXAMPLES.md b/docs/CUSTOMER_BUILD_EXAMPLES.md index 20146f9..de97cf3 100644 --- a/docs/CUSTOMER_BUILD_EXAMPLES.md +++ b/docs/CUSTOMER_BUILD_EXAMPLES.md @@ -20,7 +20,7 @@ webdrop_bridge/ python build/scripts/build_windows.py --msi ``` -**Result:** `WebDropBridge--win-x64.msi` with your packaged bootstrap defaults bundled. +**Result:** `WebDropBridge-x.x.x-Setup.msi` with your `.env` configuration bundled. --- @@ -47,7 +47,7 @@ webdrop_bridge/ **Customer Config Example:** `deploy/customer_configs/acme_corp.env` ```dotenv APP_NAME=WebDrop Bridge - ACME Corp Edition -BRAND_ID=acme_corp +APP_VERSION=1.0.0 WEBAPP_URL=https://acme-drop.example.com/drop ALLOWED_ROOTS=Z:/acme_files/,C:/Users/Public/ACME LOG_LEVEL=INFO @@ -72,9 +72,9 @@ python build/scripts/build_windows.py --msi --env-file deploy/customer_configs/i python build/scripts/build_windows.py --msi --env-file deploy/customer_configs/wayne_enterprises.env ``` -**Result:** Four separate MSI files, for example: -- `WebDropBridge--win-x64.msi` (default brand) -- `AcmeBridge--win-x64.msi` (if the customer build uses its own asset prefix) +**Result:** Four separate MSI files: +- `WebDropBridge-1.0.0-Setup.msi` (ACME - says "ACME Corp Edition") +- `WebDropBridge-1.0.0-Setup.msi` (Globex - say "Globex Edition") - etc. --- diff --git a/docs/PACKAGE_MANAGER_SUPPORT.md b/docs/PACKAGE_MANAGER_SUPPORT.md index 022fbdf..e49d914 100644 --- a/docs/PACKAGE_MANAGER_SUPPORT.md +++ b/docs/PACKAGE_MANAGER_SUPPORT.md @@ -20,16 +20,16 @@ WebDropBridge supports installation via package managers, making it easier for u # 1. Build the Chocolatey package cd build/chocolatey python ../../build/scripts/build_windows.py --msi -certutil -hashfile "../../build/dist/windows/webdrop_bridge/WebDropBridge--win-x64.msi" SHA256 +certutil -hashfile "../../build/dist/windows/WebDropBridge_Setup.msi" SHA256 # Update checksum in tools/chocolateyInstall.ps1 choco pack webdrop-bridge.nuspec -# 2. Share webdrop-bridge..nupkg +# 2. Share webdrop-bridge.0.8.0.nupkg # File share: \\server\packages\ # USB drive, email, Forgejo releases, etc. # 3. Users install it -# choco install webdrop-bridge..nupkg -s "\\server\packages" +# choco install webdrop-bridge.0.8.0.nupkg -s "\\server\packages" ``` **Advantages:** @@ -56,21 +56,21 @@ choco pack webdrop-bridge.nuspec python build/scripts/build_windows.py --msi # 2. Calculate SHA256 checksum of the MSI -certutil -hashfile "build/dist/windows/webdrop_bridge/WebDropBridge--win-x64.msi" SHA256 +certutil -hashfile "build/dist/windows/WebDropBridge_Setup.msi" SHA256 # 3. Update the checksum in build/chocolatey/tools/chocolateyInstall.ps1 # Replace: $Checksum = '' # With: $Checksum = 'YOUR_SHA256_HASH' # 4. Update version in chocolatey/webdrop-bridge.nuspec -# X.Y.Z +# 0.8.0 # 5. Create the package cd build/chocolatey choco pack webdrop-bridge.nuspec ``` -This creates `webdrop-bridge..nupkg` +This creates `webdrop-bridge.0.8.0.nupkg` ### Publishing to Chocolatey @@ -83,7 +83,7 @@ Host on your own NuGet server (Azure Artifacts, Artifactory, ProGet, etc.): choco source add -n=internal-repo -s "https://your-artifactory.internal/nuget/chocolatey/" # Push package to internal repo -nuget push webdrop-bridge..nupkg -Source https://your-artifactory.internal/nuget/chocolatey/ -ApiKey YOUR_API_KEY +nuget push webdrop-bridge.0.8.0.nupkg -Source https://your-artifactory.internal/nuget/chocolatey/ -ApiKey YOUR_API_KEY # Users install from internal repo (already configured) choco install webdrop-bridge @@ -95,7 +95,7 @@ If you want public distribution (requires community maintainer account): ```bash # Push to community repo -choco push webdrop-bridge..nupkg --api-key YOUR_CHOCOLATEY_API_KEY +choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_CHOCOLATEY_API_KEY ``` **Option 3: No Repository (Direct Distribution)** @@ -103,8 +103,8 @@ choco push webdrop-bridge..nupkg --api-key YOUR_CHOCOLATEY_API_KEY Share the `.nupkg` file directly, users install locally: ```powershell -# User downloads webdrop-bridge..nupkg and runs: -choco install webdrop-bridge..nupkg -s C:\path\to\package\folder +# User downloads webdrop-bridge.0.8.0.nupkg and runs: +choco install webdrop-bridge.0.8.0.nupkg -s C:\path\to\package\folder ``` ### User Installation @@ -119,7 +119,7 @@ choco install webdrop-bridge choco install webdrop-bridge # If distributing directly -choco install webdrop-bridge..nupkg -s "\\network\share\packages" +choco install webdrop-bridge.0.8.0.nupkg -s "\\network\share\packages" ``` ## Homebrew (macOS) @@ -183,11 +183,11 @@ Submit to `homebrew/casks` (requires more maintenance but no separate tap): bash build/scripts/build_macos.sh # 2. Calculate SHA256 checksum -shasum -a 256 "build/dist/macos/webdrop_bridge/WebDropBridge--macos-universal.dmg" +shasum -a 256 "build/dist/macos/WebDropBridge_Setup.dmg" # 3. Update formula with checksum and URL # build/homebrew/webdrop-bridge.rb -# - url: https://git.him-tools.de/...releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-macos-universal.dmg +# - url: https://git.him-tools.de/...releases/download/vX.X.X/WebDropBridge_Setup.dmg # - sha256: YOUR_SHA256_HASH ``` @@ -210,7 +210,7 @@ webdrop-bridge --version # If CLI exists, or check Applications folder ### Step 1: Build Release ```bash -# Release vX.Y.Z +# Release v0.8.0 # Windows MSI python build/scripts/build_windows.py --msi @@ -224,8 +224,8 @@ bash build/scripts/build_macos.sh Tag and upload installers to Forgejo: ```bash -git tag -a vX.Y.Z -m "Release X.Y.Z" -git push upstream vX.Y.Z +git tag -a v0.8.0 -m "Release 0.8.0" +git push upstream v0.8.0 # Upload MSI and DMG to Forgejo release page ``` @@ -234,10 +234,10 @@ git push upstream vX.Y.Z ```bash # Windows -certutil -hashfile WebDropBridge--win-x64.msi SHA256 +certutil -hashfile WebDropBridge_Setup.msi SHA256 # macOS -shasum -a 256 WebDropBridge--macos-universal.dmg +shasum -a 256 WebDropBridge_Setup.dmg ``` ### Step 4: Update Package Manager Files @@ -258,7 +258,7 @@ sha256 "MACOS_SHA256_HASH" ```powershell cd build/chocolatey choco pack -choco install webdrop-bridge..nupkg -s . +choco install webdrop-bridge.0.8.0.nupkg -s . ``` **Homebrew (with tap):** @@ -270,7 +270,7 @@ brew install ./build/homebrew/webdrop-bridge.rb **Chocolatey:** ```powershell -choco push webdrop-bridge..nupkg --api-key YOUR_KEY +choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY ``` **Homebrew:** @@ -343,7 +343,7 @@ This works for: ### Chocolatey Issues **Package won't install:** -- Verify checksum: `certutil -hashfile WebDropBridge--win-x64.msi SHA256` +- Verify checksum: `certutil -hashfile WebDropBridge_Setup.msi SHA256` - Check MSI exists at URL: `wget URL` - Verify SHA256 matches in `chocolateyInstall.ps1` @@ -356,7 +356,7 @@ This works for: **Formula won't install:** - Validate syntax: `brew audit --formula webdrop-bridge.rb` - Check URL is accessible: `curl -I URL` -- Verify SHA256: `shasum -a 256 WebDropBridge--macos-universal.dmg` +- Verify SHA256: `shasum -a 256 WebDropBridge_Setup.dmg` **Upgrade fails:** - Remove old version: `brew uninstall webdrop-bridge` @@ -375,7 +375,7 @@ This works for: 1. **Easiest: Direct Distribution** ✅ - Share `.nupkg` file via file share or email - - Users: `choco install webdrop-bridge..nupkg -s "\\share\packages"` + - Users: `choco install webdrop-bridge.0.8.0.nupkg -s "\\share\packages"` - No infrastructure needed - No maintainer account required