feat: Update documentation for version 0.9.1, including changelog, configuration, and package manager support
Some checks failed
Tests & Quality Checks / Test on Python 3.11 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.10 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-2 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-2 (push) Has been cancelled
Tests & Quality Checks / Build Artifacts (push) Has been cancelled
Tests & Quality Checks / Build Artifacts-1 (push) Has been cancelled
Some checks failed
Tests & Quality Checks / Test on Python 3.11 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-1 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.10 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.11-2 (push) Has been cancelled
Tests & Quality Checks / Test on Python 3.12-2 (push) Has been cancelled
Tests & Quality Checks / Build Artifacts (push) Has been cancelled
Tests & Quality Checks / Build Artifacts-1 (push) Has been cancelled
This commit is contained in:
parent
1054266d0e
commit
ac10fdcbdd
11 changed files with 196 additions and 159 deletions
|
|
@ -12,4 +12,4 @@ All notable changes to this project will be documented in this file.
|
|||
### 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.
|
||||
|
|
|
|||
|
|
@ -36,7 +36,10 @@ Create a `config.json` file with the following structure:
|
|||
"log_file": "logs/webdrop_bridge.log",
|
||||
"window_width": 1024,
|
||||
"window_height": 768,
|
||||
"enable_logging": true
|
||||
"enable_logging": true,
|
||||
"language": "auto",
|
||||
"active_branding_id": "default",
|
||||
"brand_id": "agravity"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -99,6 +102,19 @@ 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"`
|
||||
|
|
@ -149,6 +165,14 @@ 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`:
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Please be respectful and constructive in all interactions. We're building a welc
|
|||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Python 3.10+
|
||||
- Python 3.9+
|
||||
- Git
|
||||
- Familiarity with Qt/PySide6 or willingness to learn
|
||||
|
||||
|
|
|
|||
|
|
@ -1051,7 +1051,7 @@ Help Menu
|
|||
|
||||
**Core:**
|
||||
- PySide6 6.6.0+
|
||||
- Python 3.10+
|
||||
- Python 3.9+
|
||||
|
||||
**Optional:**
|
||||
- PyInstaller (building)
|
||||
|
|
|
|||
|
|
@ -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 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
|
||||
# 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
|
||||
|
||||
# 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
|
||||
# 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
|
||||
|
||||
# macOS - download v0.8.0 DMG
|
||||
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Windows (PowerShell) - Full Control Script
|
||||
|
|
@ -168,7 +168,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0
|
|||
.\build\scripts\download_release.ps1 -OutputDir "C:\Installers"
|
||||
|
||||
# Download specific version
|
||||
.\build\scripts\download_release.ps1 -Version "0.8.0"
|
||||
.\build\scripts\download_release.ps1 -Version "0.9.1"
|
||||
|
||||
# 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.8.0
|
|||
./build/scripts/download_release.sh latest ~/Downloads
|
||||
|
||||
# Download specific version
|
||||
./build/scripts/download_release.sh 0.8.0
|
||||
./build/scripts/download_release.sh 0.9.1
|
||||
|
||||
# Skip checksum verification
|
||||
./build/scripts/download_release.sh latest --no-verify
|
||||
|
|
|
|||
95
README.md
95
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.)
|
||||
|
||||
  
|
||||
  
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -19,23 +19,25 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a
|
|||
|
||||
## Features
|
||||
|
||||
- ✅ **Qt-based Architecture** - Professional Windows support via PySide6 (macOS support planned)
|
||||
- ✅ **Qt-based Architecture** - Professional cross-platform desktop app via PySide6 for Windows and macOS
|
||||
- ✅ **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** - Profile-based settings with validation
|
||||
- ✅ **Settings Dialog** - Professional UI for path, URL, logging, and window configuration
|
||||
- ✅ **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
|
||||
- ✅ **Auto-Update System** - Automatic release detection via Forgejo API
|
||||
- ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS
|
||||
- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests (80%+ coverage)
|
||||
- ✅ **Continuous Testing** - GitHub Actions test automation
|
||||
- ✅ **Comprehensive Testing** - Unit and integration coverage across core modules
|
||||
- ✅ **Continuous Testing** - Automated CI validation
|
||||
- ✅ **Structured Logging** - File-based logging with configurable levels
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Requirements
|
||||
- Python 3.10+
|
||||
- Windows 10/11
|
||||
- Python 3.9+
|
||||
- Windows 10/11 or macOS 12+
|
||||
- 200 MB disk space (includes Chromium from PyInstaller)
|
||||
|
||||
### Installation from Pre-Built Release (Recommended)
|
||||
|
|
@ -58,11 +60,11 @@ brew upgrade webdrop-bridge # Update to latest version
|
|||
**Option 2: Direct wget (if you know the version)**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
# 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
|
||||
|
||||
# Example for v0.8.0:
|
||||
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/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
|
||||
```
|
||||
|
||||
**Option 3: Automated script (auto-detects platform)**
|
||||
|
|
@ -93,6 +95,7 @@ python -m venv venv
|
|||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
pip install -e .
|
||||
|
||||
# Run application
|
||||
python -m webdrop_bridge.main
|
||||
|
|
@ -103,6 +106,7 @@ python -m webdrop_bridge.main
|
|||
```bash
|
||||
# Install development dependencies
|
||||
pip install -r requirements-dev.txt
|
||||
pip install -e .
|
||||
|
||||
# Run tests
|
||||
pytest tests -v
|
||||
|
|
@ -178,42 +182,36 @@ webdrop-bridge/
|
|||
|
||||
## Configuration
|
||||
|
||||
WebDrop Bridge supports two configuration methods:
|
||||
WebDrop Bridge supports persisted JSON configuration plus optional bootstrap environment defaults.
|
||||
|
||||
### 1. Settings Dialog (Recommended)
|
||||
### 1. Settings Dialog / JSON Config (Recommended)
|
||||
Launch the application and access the Settings menu to configure:
|
||||
- **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
|
||||
- **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
|
||||
|
||||
Profiles are saved in `~/.webdrop_bridge/profiles/`
|
||||
Saved settings are written to the brand-specific application config directory as `config.json`.
|
||||
|
||||
### 2. Environment Variables
|
||||
Create a `.env` file in the project root. Available settings:
|
||||
### 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.
|
||||
|
||||
```bash
|
||||
# Application
|
||||
APP_NAME=WebDrop Bridge
|
||||
APP_VERSION=1.0.0
|
||||
|
||||
# Paths (comma-separated)
|
||||
BRAND_ID=webdrop_bridge
|
||||
WEBAPP_URL=https://dev.agravity.io/
|
||||
ALLOWED_ROOTS=Z:/,C:/Users/Public
|
||||
|
||||
# Web URLs (empty = no restriction, items = kiosk mode)
|
||||
ALLOWED_URLS=
|
||||
|
||||
# Interface
|
||||
WEBAPP_URL=file:///./webapp/index.html
|
||||
LANGUAGE=auto
|
||||
LOG_LEVEL=INFO
|
||||
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.
|
||||
|
|
@ -272,11 +270,20 @@ python build/scripts/build_windows.py --msi --code-sign
|
|||
```
|
||||
|
||||
Output:
|
||||
- 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`
|
||||
- Portable executable: `build/dist/windows/webdrop_bridge/WebDropBridge/WebDropBridge.exe`
|
||||
- Professional MSI installer: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi`
|
||||
- SHA256 checksum: `build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi.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.
|
||||
### 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-<version>-macos-universal.dmg`
|
||||
- SHA256 checksum: `build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg.sha256`
|
||||
|
||||
### Creating Releases
|
||||
|
||||
|
|
@ -314,8 +321,8 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1
|
|||
## Troubleshooting
|
||||
|
||||
### Application won't start
|
||||
- Ensure Python 3.10+ is installed
|
||||
- Check `logs/webdrop_bridge.log` for errors
|
||||
- Ensure Python 3.9+ is installed
|
||||
- Check the application log in your platform-specific app data directory
|
||||
- Verify all dependencies: `pip list`
|
||||
|
||||
### Drag-and-drop not working
|
||||
|
|
@ -332,10 +339,10 @@ powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1
|
|||
|
||||
| Platform | Version | Status | Notes |
|
||||
|----------|---------|--------|-------|
|
||||
| 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. |
|
||||
| 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 |
|
||||
|
||||
**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.
|
||||
**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.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -367,4 +374,4 @@ MIT License - see [LICENSE](LICENSE) file for details
|
|||
|
||||
---
|
||||
|
||||
**Development Phase**: Phase 4 Complete | **Last Updated**: February 18, 2026 | **Current Version**: 1.0.0 | **Python**: 3.10+ | **Qt**: PySide6 (Qt 6)
|
||||
**Development Phase**: Phase 5 Release Candidates | **Last Updated**: April 16, 2026 | **Current Version**: 0.9.1 | **Python**: 3.9+ | **Qt**: PySide6 (Qt 6)
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ build/
|
|||
|
||||
2. **Get SHA256 checksum**:
|
||||
```powershell
|
||||
certutil -hashfile build/dist/windows/WebDropBridge_Setup.msi SHA256
|
||||
certutil -hashfile build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi SHA256
|
||||
```
|
||||
|
||||
3. **Update package files**:
|
||||
|
|
@ -42,7 +42,7 @@ build/
|
|||
|
||||
5. **Publish** (requires Chocolatey API key):
|
||||
```powershell
|
||||
choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY
|
||||
choco push webdrop-bridge.<version>.nupkg --api-key YOUR_KEY
|
||||
```
|
||||
|
||||
### Homebrew Formula (macOS)
|
||||
|
|
@ -54,7 +54,7 @@ build/
|
|||
|
||||
2. **Get SHA256 checksum**:
|
||||
```bash
|
||||
shasum -a 256 build/dist/macos/WebDropBridge_Setup.dmg
|
||||
shasum -a 256 build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg
|
||||
```
|
||||
|
||||
3. **Update formula**:
|
||||
|
|
|
|||
|
|
@ -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.8.0/WebDropBridge_Setup.msi
|
||||
wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg
|
||||
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
|
||||
```
|
||||
|
||||
**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.8.0" -OutputDir "$env:USERPROFILE\Downloads"
|
||||
.\download_release.ps1 -Version "0.9.1" -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.8.0 ~/Downloads
|
||||
./build/scripts/download_release.sh 0.9.1 ~/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.8.0
|
||||
python build/scripts/sync_version.py --version 0.9.1
|
||||
```
|
||||
|
||||
## Integration Flow
|
||||
|
|
|
|||
|
|
@ -1,33 +1,60 @@
|
|||
# Configuration Management for Builds
|
||||
|
||||
This document explains how configuration is handled when building executables and installers for WebDrop Bridge.
|
||||
This document explains how configuration and branding work for development builds, packaged installers, and installed applications.
|
||||
|
||||
## Overview
|
||||
## Current Configuration Model
|
||||
|
||||
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.
|
||||
WebDrop Bridge now uses a **JSON-first runtime configuration** with optional `.env` bootstrap defaults:
|
||||
|
||||
## Configuration File
|
||||
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
|
||||
|
||||
The configuration file must be named `.env` and contains settings like:
|
||||
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
|
||||
APP_VERSION=0.7.1
|
||||
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
|
||||
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:
|
||||
If you want to use the project's default `.env` file from the repository root:
|
||||
|
||||
### Windows
|
||||
```bash
|
||||
|
|
@ -39,11 +66,11 @@ python build/scripts/build_windows.py --msi
|
|||
bash build/scripts/build_macos.sh
|
||||
```
|
||||
|
||||
**Important:** The build will **fail** if `.env` doesn't exist. This prevents accidentally shipping without configuration.
|
||||
> The build scripts currently expect a `.env` file to exist. This is intentional so packaged builds always have explicit bootstrap defaults.
|
||||
|
||||
## Building with Custom Configuration
|
||||
## Building with Custom Customer Defaults
|
||||
|
||||
For different customers or deployments, you can specify a custom `.env` file:
|
||||
For customer-specific or branded releases, provide a different `.env` file during packaging:
|
||||
|
||||
### Windows
|
||||
```bash
|
||||
|
|
@ -55,86 +82,73 @@ 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
|
||||
```
|
||||
|
||||
The custom `.env` file will be bundled into the executable and users will receive those pre-configured settings.
|
||||
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
|
||||
|
||||
If you have different customer configurations:
|
||||
|
||||
```
|
||||
```text
|
||||
webdrop_bridge/
|
||||
├── .env # Default project configuration
|
||||
├── .env.example # Template
|
||||
├── .env
|
||||
├── build/
|
||||
│ └── scripts/
|
||||
│ ├── build_windows.py
|
||||
│ └── build_macos.sh
|
||||
├── customer_configs/ # Create this for customer-specific settings
|
||||
├── customer_configs/
|
||||
│ ├── acme_corp.env
|
||||
│ ├── globex_corporation.env
|
||||
│ └── initech.env
|
||||
└── ...
|
||||
└── config.example.json
|
||||
```
|
||||
|
||||
Then build for each customer:
|
||||
Then build per customer or brand:
|
||||
|
||||
```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
|
||||
bash build/scripts/build_macos.sh --env-file customer_configs/initech.env
|
||||
```
|
||||
|
||||
Each MSI will include that customer's specific configuration (URLs, allowed paths, etc.).
|
||||
## What Gets Bundled into Installers?
|
||||
|
||||
## What Gets Bundled
|
||||
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
|
||||
|
||||
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
|
||||
After installation, the application normally saves user-controlled settings to the JSON config file in the app data directory.
|
||||
|
||||
Users **do not** need to create their own `.env` files.
|
||||
## Recommended Runtime Workflow
|
||||
|
||||
## 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
|
||||
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 (.env from project root)
|
||||
# Default build using the repository root .env
|
||||
python build/scripts/build_windows.py --msi
|
||||
|
||||
# Custom .env file
|
||||
# Customer-specific defaults
|
||||
python build/scripts/build_windows.py --msi --env-file customer_configs/acme.env
|
||||
|
||||
# Without MSI (just EXE)
|
||||
# Without MSI (just the packaged executable)
|
||||
python build/scripts/build_windows.py
|
||||
|
||||
# Sign executable (requires CODE_SIGN_CERT env var)
|
||||
# Sign executable (requires signing setup)
|
||||
python build/scripts/build_windows.py --msi --code-sign
|
||||
```
|
||||
|
||||
### macOS
|
||||
```bash
|
||||
# Default (.env from project root)
|
||||
# Default build using the repository root .env
|
||||
bash build/scripts/build_macos.sh
|
||||
|
||||
# Custom .env file
|
||||
# Customer-specific defaults
|
||||
bash build/scripts/build_macos.sh --env-file customer_configs/acme.env
|
||||
|
||||
# Sign app (requires Apple developer certificate)
|
||||
|
|
@ -144,19 +158,11 @@ bash build/scripts/build_macos.sh --sign
|
|||
bash build/scripts/build_macos.sh --notarize
|
||||
```
|
||||
|
||||
## Configuration Validation
|
||||
## Validation Notes
|
||||
|
||||
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.)
|
||||
1. the specified `.env` file exists,
|
||||
2. packaging metadata can be resolved, and
|
||||
3. the resulting installer assets are created successfully.
|
||||
|
||||
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.
|
||||
If you need the full runtime JSON schema, see `CONFIG_README.md`.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ webdrop_bridge/
|
|||
python build/scripts/build_windows.py --msi
|
||||
```
|
||||
|
||||
**Result:** `WebDropBridge-x.x.x-Setup.msi` with your `.env` configuration bundled.
|
||||
**Result:** `WebDropBridge-<version>-win-x64.msi` with your packaged bootstrap defaults bundled.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -47,7 +47,7 @@ webdrop_bridge/
|
|||
**Customer Config Example:** `deploy/customer_configs/acme_corp.env`
|
||||
```dotenv
|
||||
APP_NAME=WebDrop Bridge - ACME Corp Edition
|
||||
APP_VERSION=1.0.0
|
||||
BRAND_ID=acme_corp
|
||||
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:
|
||||
- `WebDropBridge-1.0.0-Setup.msi` (ACME - says "ACME Corp Edition")
|
||||
- `WebDropBridge-1.0.0-Setup.msi` (Globex - say "Globex Edition")
|
||||
**Result:** Four separate MSI files, for example:
|
||||
- `WebDropBridge-<version>-win-x64.msi` (default brand)
|
||||
- `AcmeBridge-<version>-win-x64.msi` (if the customer build uses its own asset prefix)
|
||||
- etc.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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/WebDropBridge_Setup.msi" SHA256
|
||||
certutil -hashfile "../../build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.msi" SHA256
|
||||
# Update checksum in tools/chocolateyInstall.ps1
|
||||
choco pack webdrop-bridge.nuspec
|
||||
|
||||
# 2. Share webdrop-bridge.0.8.0.nupkg
|
||||
# 2. Share webdrop-bridge.<version>.nupkg
|
||||
# File share: \\server\packages\
|
||||
# USB drive, email, Forgejo releases, etc.
|
||||
|
||||
# 3. Users install it
|
||||
# choco install webdrop-bridge.0.8.0.nupkg -s "\\server\packages"
|
||||
# choco install webdrop-bridge.<version>.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/WebDropBridge_Setup.msi" SHA256
|
||||
certutil -hashfile "build/dist/windows/webdrop_bridge/WebDropBridge-<version>-win-x64.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
|
||||
# <version>0.8.0</version>
|
||||
# <version>X.Y.Z</version>
|
||||
|
||||
# 5. Create the package
|
||||
cd build/chocolatey
|
||||
choco pack webdrop-bridge.nuspec
|
||||
```
|
||||
|
||||
This creates `webdrop-bridge.0.8.0.nupkg`
|
||||
This creates `webdrop-bridge.<version>.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.0.8.0.nupkg -Source https://your-artifactory.internal/nuget/chocolatey/ -ApiKey YOUR_API_KEY
|
||||
nuget push webdrop-bridge.<version>.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.0.8.0.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
|
||||
choco push webdrop-bridge.<version>.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
|
||||
```
|
||||
|
||||
**Option 3: No Repository (Direct Distribution)**
|
||||
|
|
@ -103,8 +103,8 @@ choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_CHOCOLATEY_API_KEY
|
|||
Share the `.nupkg` file directly, users install locally:
|
||||
|
||||
```powershell
|
||||
# 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 downloads webdrop-bridge.<version>.nupkg and runs:
|
||||
choco install webdrop-bridge.<version>.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.0.8.0.nupkg -s "\\network\share\packages"
|
||||
choco install webdrop-bridge.<version>.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/WebDropBridge_Setup.dmg"
|
||||
shasum -a 256 "build/dist/macos/webdrop_bridge/WebDropBridge-<version>-macos-universal.dmg"
|
||||
|
||||
# 3. Update formula with checksum and URL
|
||||
# build/homebrew/webdrop-bridge.rb
|
||||
# - url: https://git.him-tools.de/...releases/download/vX.X.X/WebDropBridge_Setup.dmg
|
||||
# - url: https://git.him-tools.de/...releases/download/vX.Y.Z/WebDropBridge-X.Y.Z-macos-universal.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 v0.8.0
|
||||
# Release vX.Y.Z
|
||||
|
||||
# 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 v0.8.0 -m "Release 0.8.0"
|
||||
git push upstream v0.8.0
|
||||
git tag -a vX.Y.Z -m "Release X.Y.Z"
|
||||
git push upstream vX.Y.Z
|
||||
|
||||
# Upload MSI and DMG to Forgejo release page
|
||||
```
|
||||
|
|
@ -234,10 +234,10 @@ git push upstream v0.8.0
|
|||
|
||||
```bash
|
||||
# Windows
|
||||
certutil -hashfile WebDropBridge_Setup.msi SHA256
|
||||
certutil -hashfile WebDropBridge-<version>-win-x64.msi SHA256
|
||||
|
||||
# macOS
|
||||
shasum -a 256 WebDropBridge_Setup.dmg
|
||||
shasum -a 256 WebDropBridge-<version>-macos-universal.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.0.8.0.nupkg -s .
|
||||
choco install webdrop-bridge.<version>.nupkg -s .
|
||||
```
|
||||
|
||||
**Homebrew (with tap):**
|
||||
|
|
@ -270,7 +270,7 @@ brew install ./build/homebrew/webdrop-bridge.rb
|
|||
|
||||
**Chocolatey:**
|
||||
```powershell
|
||||
choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY
|
||||
choco push webdrop-bridge.<version>.nupkg --api-key YOUR_KEY
|
||||
```
|
||||
|
||||
**Homebrew:**
|
||||
|
|
@ -343,7 +343,7 @@ This works for:
|
|||
### Chocolatey Issues
|
||||
|
||||
**Package won't install:**
|
||||
- Verify checksum: `certutil -hashfile WebDropBridge_Setup.msi SHA256`
|
||||
- Verify checksum: `certutil -hashfile WebDropBridge-<version>-win-x64.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_Setup.dmg`
|
||||
- Verify SHA256: `shasum -a 256 WebDropBridge-<version>-macos-universal.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.0.8.0.nupkg -s "\\share\packages"`
|
||||
- Users: `choco install webdrop-bridge.<version>.nupkg -s "\\share\packages"`
|
||||
- No infrastructure needed
|
||||
- No maintainer account required
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue