From 87884935c9ed8a01a1c53259afdec7804b84c342 Mon Sep 17 00:00:00 2001 From: claudi Date: Tue, 3 Mar 2026 09:33:06 +0100 Subject: [PATCH] feat: implement package manager support for Windows and macOS, including Chocolatey and Homebrew configurations --- DEVELOPMENT_PLAN.md | 34 +- QUICKSTART.md | 35 +- README.md | 21 +- build/chocolatey/tools/chocolateyInstall.ps1 | 47 +++ .../chocolatey/tools/chocolateyUninstall.ps1 | 38 ++ build/chocolatey/webdrop-bridge.nuspec | 28 ++ build/homebrew/webdrop-bridge.rb | 48 +++ build/package-managers/README.md | 126 ++++++ docs/PACKAGE_MANAGER_SUPPORT.md | 391 ++++++++++++++++++ 9 files changed, 758 insertions(+), 10 deletions(-) create mode 100644 build/chocolatey/tools/chocolateyInstall.ps1 create mode 100644 build/chocolatey/tools/chocolateyUninstall.ps1 create mode 100644 build/chocolatey/webdrop-bridge.nuspec create mode 100644 build/homebrew/webdrop-bridge.rb create mode 100644 build/package-managers/README.md create mode 100644 docs/PACKAGE_MANAGER_SUPPORT.md diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md index fa8146e..e5460e6 100644 --- a/DEVELOPMENT_PLAN.md +++ b/DEVELOPMENT_PLAN.md @@ -1197,6 +1197,27 @@ February 2026 --- +### Decision: Package Manager Support (Phase 5) + +**Options:** +1. Only direct downloads +2. Single package manager (Chocolatey OR Homebrew) +3. Multiple package managers (Chocolatey AND Homebrew) with custom taps + +**Decision**: **Multi-channel distribution via package managers** +- **Windows**: Chocolatey community repository or internal NuGet +- **macOS**: Custom Homebrew tap on Forgejo (HIM-public/homebrew-webdrop-bridge) +- **Fallback**: Direct wget downloads + built-in auto-update system +- **Implementation**: Supports both official repos and internal/private hosting + +**Implementation Details:** +- Chocolatey: `build/chocolatey/` with .nuspec manifest +- Homebrew: `build/homebrew/` with Ruby formula +- Auto-download checksums from Forgejo releases +- Documentation in `docs/PACKAGE_MANAGER_SUPPORT.md` + +--- + ### Decision: Telemetry **Options:** @@ -1255,23 +1276,24 @@ Phase 4 Complete - Professional Features & Auto-Update system fully implemented. - Cross-platform testing on Windows 10/11, macOS 12-14 - Security hardening and final audit - Performance optimization (drag latency < 50ms) + - **Package Manager Setup** (NEW): + - Chocolatey packaging and publishing workflow + - Homebrew tap creation for custom distribution + - Documentation for package manager support 2. **Testing & Validation**: - Run full test suite on both platforms - User acceptance testing with real-world scenarios + - Package manager installation testing - Documentation review and finalization 3. **Finalization**: - Announce stable release v1.0.0 - Publish installers to Forgejo Packages + - Publish to Chocolatey (community or internal) + - Create and publish Homebrew tap - Enable auto-update system for users -3. **Finalization**: - - Code signing for Windows MSI (optional) - - Apple notarization for macOS DMG (future) - - Create stable v1.0.0 release - - Publish to Forgejo Packages - --- ## Document Control diff --git a/QUICKSTART.md b/QUICKSTART.md index f32ce7c..5c9611e 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -110,7 +110,40 @@ tox ### Installing from Release (wget) -Download pre-built installers from Forgejo releases using **wget** (useful for enterprise deployments, automated scripts, or initial setup before the built-in update mechanism): +Download pre-built installers from Forgejo releases using **wget**, **package managers**, or **automated scripts** (useful for enterprise deployments, automated scripts, or initial setup before the built-in update mechanism): + +#### Package Manager (Easiest) + +**Windows (Chocolatey)** + +```powershell +# Install +choco install webdrop-bridge + +# Upgrade to latest +choco upgrade webdrop-bridge + +# Uninstall +choco uninstall webdrop-bridge +``` + +**macOS (Homebrew with custom tap)** + +```bash +# Add tap (one-time setup) +brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git + +# Install +brew install webdrop-bridge + +# Upgrade +brew upgrade webdrop-bridge + +# Uninstall +brew uninstall webdrop-bridge +``` + +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) diff --git a/README.md b/README.md index ad53590..191e608 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,22 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a ### Installation from Pre-Built Release (Recommended) -**Simplest Method: Direct wget (if you know the version)** +**Option 1: Package Manager (Recommended for most users)** + +```powershell +# Windows - Chocolatey +choco install webdrop-bridge +choco upgrade webdrop-bridge # Update when new version available +``` + +```bash +# macOS - Homebrew (with custom tap) +brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git +brew install webdrop-bridge +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) @@ -50,7 +65,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/VERSIO wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.msi ``` -**Alternative: Automated script (auto-detects platform)** +**Option 3: Automated script (auto-detects platform)** ```bash # Windows (PowerShell) @@ -60,7 +75,7 @@ wget https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0 ./build/scripts/download_release.sh ``` -For more installation options and details, see [QUICKSTART.md](QUICKSTART.md#installing-from-release-wget) +For more installation options and details, see [QUICKSTART.md](QUICKSTART.md#installing-from-release-wget) and [PACKAGE_MANAGER_SUPPORT.md](docs/PACKAGE_MANAGER_SUPPORT.md) ### Installation from Source diff --git a/build/chocolatey/tools/chocolateyInstall.ps1 b/build/chocolatey/tools/chocolateyInstall.ps1 new file mode 100644 index 0000000..619370a --- /dev/null +++ b/build/chocolatey/tools/chocolateyInstall.ps1 @@ -0,0 +1,47 @@ +$ErrorActionPreference = 'Stop' + +$PackageName = 'webdrop-bridge' +$Version = '0.8.0' +$Url = "https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v$Version/WebDropBridge_Setup.msi" +$Checksum = '' # Update with actual SHA256 checksum from release +$ChecksumType = 'sha256' + +# Create temporary directory for download +$TempDir = Join-Path $env:TEMP "webdrop-bridge-$Version" +New-Item -ItemType Directory -Path $TempDir -Force | Out-Null + +try { + # Download MSI installer + Write-Host "Downloading WebDropBridge $Version MSI installer..." + $InstallerPath = Join-Path $TempDir "WebDropBridge_Setup.msi" + + Get-ChocolateyWebFile -PackageName $PackageName ` + -FileFullPath $InstallerPath ` + -Url $Url ` + -Checksum $Checksum ` + -ChecksumType $ChecksumType + + # Install MSI + Write-Host "Installing WebDropBridge..." + $InstallArgs = @( + '/i' + "`"$InstallerPath`"" + '/quiet' # Silent installation + '/norestart' # Don't restart immediately + ) + + Invoke-ChocolateyInstall -PackageName $PackageName ` + -File 'msiexec.exe' ` + -FileArgs $InstallArgs ` + -ValidExitCodes @(0, 3010) # 0=success, 3010=restart needed + + Write-Host "WebDropBridge installed successfully" +} catch { + Write-Error "Installation failed: $_" + exit 1 +} finally { + # Cleanup + if (Test-Path $TempDir) { + Remove-Item $TempDir -Recurse -Force -ErrorAction SilentlyContinue + } +} diff --git a/build/chocolatey/tools/chocolateyUninstall.ps1 b/build/chocolatey/tools/chocolateyUninstall.ps1 new file mode 100644 index 0000000..599426b --- /dev/null +++ b/build/chocolatey/tools/chocolateyUninstall.ps1 @@ -0,0 +1,38 @@ +$ErrorActionPreference = 'Stop' + +$PackageName = 'webdrop-bridge' + +try { + # Find installed version + $UninstallPath = Get-ChildItem HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall | + Where-Object { $_.GetValue('DisplayName') -like '*WebDropBridge*' } | + Select-Object -First 1 + + if ($UninstallPath) { + $UninstallString = $UninstallPath.GetValue('UninstallString') + + # Extract MSI Product ID from uninstall string + if ($UninstallString -match '{[A-F0-9-]+}') { + $ProductId = $matches[0] + + Write-Host "Uninstalling WebDropBridge (Product ID: $ProductId)..." + + $UninstallArgs = @( + '/x' + $ProductId + '/quiet' + '/norestart' + ) + + & 'msiexec.exe' @UninstallArgs + + Write-Host "WebDropBridge uninstalled successfully" + } else { + Write-Warning "Could not extract Product ID from uninstall string" + } + } else { + Write-Warning "WebDropBridge is not installed" + } +} catch { + Write-Error "Uninstall failed: $_" +} diff --git a/build/chocolatey/webdrop-bridge.nuspec b/build/chocolatey/webdrop-bridge.nuspec new file mode 100644 index 0000000..18b160c --- /dev/null +++ b/build/chocolatey/webdrop-bridge.nuspec @@ -0,0 +1,28 @@ + + + + webdrop-bridge + 0.8.0 + https://git.him-tools.de/HIM-public/webdrop-bridge + HIM-public + WebDrop Bridge + HIM-public + https://git.him-tools.de/HIM-public/webdrop-bridge/blob/main/LICENSE + https://git.him-tools.de/HIM-public/webdrop-bridge + https://git.him-tools.de/HIM-public/webdrop-bridge/issues + +Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.) + +Converts text-based drag-and-drop operations from embedded web applications into native file operations recognized by professional desktop applications. + + Intelligent drag-and-drop file bridge for web to desktop applications + https://git.him-tools.de/HIM-public/webdrop-bridge/releases/tag/v0.8.0 + drag-drop file-transfer qt pyside6 desktop automation + + + + + + + + diff --git a/build/homebrew/webdrop-bridge.rb b/build/homebrew/webdrop-bridge.rb new file mode 100644 index 0000000..605f03b --- /dev/null +++ b/build/homebrew/webdrop-bridge.rb @@ -0,0 +1,48 @@ +class WebdropBridge < Formula + desc "Intelligent drag-and-drop file bridge for web to desktop applications" + homepage "https://git.him-tools.de/HIM-public/webdrop-bridge" + version "0.8.0" + + # ARM64 (Apple Silicon) + on_arm do + url "https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg" + sha256 "" # Update with actual checksum + end + + # Intel x86_64 + on_intel do + url "https://git.him-tools.de/HIM-public/webdrop-bridge/releases/download/v0.8.0/WebDropBridge_Setup.dmg" + sha256 "" # Update with actual checksum (may be same as ARM64 if universal binary) + end + + license "MIT" + + livecheck do + url "https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/releases/latest" + strategy :json do |json| + json["tag_name"]&.strip&.sub(/^v/, "") + end + end + + app "WebDropBridge.app" + + post_install do + # Create user defaults directory if needed + system "mkdir", "-p", "#{Dir.home}/.webdrop-bridge" + end + + def caveats + <<~EOS + WebDropBridge has been installed. + + Configuration files are stored in: ~/.webdrop-bridge/ + Logs are written to: ~/.webdrop-bridge/logs/ + + To start the application: + - Open Applications > WebDropBridge + - Or run: open /Applications/WebDropBridge.app + + For documentation: https://git.him-tools.de/HIM-public/webdrop-bridge + EOS + end +end diff --git a/build/package-managers/README.md b/build/package-managers/README.md new file mode 100644 index 0000000..7f0a400 --- /dev/null +++ b/build/package-managers/README.md @@ -0,0 +1,126 @@ +# Package Manager Distributions + +This directory contains package manager configurations for distributing WebDropBridge across different platforms. + +## Directory Structure + +``` +build/ +├── chocolatey/ # Windows - Chocolatey/NuGet package +│ ├── webdrop-bridge.nuspec # Package manifest +│ └── tools/ +│ ├── chocolateyInstall.ps1 # Installation script +│ └── chocolateyUninstall.ps1 # Uninstallation script +│ +└── homebrew/ # macOS - Homebrew formula + └── webdrop-bridge.rb # Homebrew formula +``` + +## Quick Start + +### Chocolatey Package (Windows) + +1. **Build MSI installer**: + ```bash + python build/scripts/build_windows.py --msi + ``` + +2. **Get SHA256 checksum**: + ```powershell + certutil -hashfile build/dist/windows/WebDropBridge_Setup.msi SHA256 + ``` + +3. **Update package files**: + - `build/chocolatey/webdrop-bridge.nuspec` - update `` + - `build/chocolatey/tools/chocolateyInstall.ps1` - update `$Version` and `$Checksum` + +4. **Package it** (requires Chocolatey CLI): + ```powershell + cd build/chocolatey + choco pack webdrop-bridge.nuspec + ``` + +5. **Publish** (requires Chocolatey API key): + ```powershell + choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY + ``` + +### Homebrew Formula (macOS) + +1. **Build DMG installer**: + ```bash + bash build/scripts/build_macos.sh + ``` + +2. **Get SHA256 checksum**: + ```bash + shasum -a 256 build/dist/macos/WebDropBridge_Setup.dmg + ``` + +3. **Update formula**: + - `build/homebrew/webdrop-bridge.rb` - update `version` and `sha256` + +4. **Test locally**: + ```bash + brew audit --formula build/homebrew/webdrop-bridge.rb + brew install build/homebrew/webdrop-bridge.rb + ``` + +5. **Publish** (create Forgejo tap or submit to official Homebrew): + - Option A: Create `homebrew-webdrop-bridge` tap on Forgejo + - Option B: Submit to `homebrew/casks` on GitHub + +## Publishing Strategy + +### Recommended Approach for HIM + +1. **Chocolatey**: + - Host in internal Artifactory/Azure Artifacts NuGet repository + - OR submit to Chocolatey community (chocolatey.org) + - Users: `choco install webdrop-bridge` + +2. **Homebrew**: + - Create custom tap: `HIM-public/homebrew-webdrop-bridge` on Forgejo + - Users add tap: `brew tap HIM-public/webdrop-bridge https://git.him-tools.de/...` + - Users: `brew install webdrop-bridge` + +3. **Fallback**: + - Direct wget/downloads from Forgejo releases + - Built-in auto-update system in app + +## Release Checklist + +When releasing version X.Y.Z: + +- [ ] Build Windows MSI: `python build/scripts/build_windows.py --msi` +- [ ] Build macOS DMG: `bash build/scripts/build_macos.sh` +- [ ] Calculate checksums (certutil / shasum) +- [ ] Create Forgejo release with installers +- [ ] Update `build/chocolatey/webdrop-bridge.nuspec` version +- [ ] Update `build/chocolatey/tools/chocolateyInstall.ps1` version & checksum +- [ ] Update `build/homebrew/webdrop-bridge.rb` version & checksum +- [ ] Test Chocolatey package locally +- [ ] Test Homebrew formula locally +- [ ] Publish to package managers + +## User Installation Commands + +After publishing: + +```powershell +# Windows +choco install webdrop-bridge +``` + +```bash +# macOS +brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git +brew install webdrop-bridge +``` + +## References + +- [Full Documentation](../../docs/PACKAGE_MANAGER_SUPPORT.md) +- [Chocolatey Docs](https://docs.chocolatey.org/) +- [Homebrew Docs](https://docs.brew.sh/) +- [Forgejo API](https://docs.gitea.com/api/1.22/) diff --git a/docs/PACKAGE_MANAGER_SUPPORT.md b/docs/PACKAGE_MANAGER_SUPPORT.md new file mode 100644 index 0000000..e49d914 --- /dev/null +++ b/docs/PACKAGE_MANAGER_SUPPORT.md @@ -0,0 +1,391 @@ +# Package Manager Support for WebDropBridge + +This document explains how to build and publish WebDropBridge to package managers like Chocolatey (Windows) and Homebrew (macOS). + +## Overview + +WebDropBridge supports installation via package managers, making it easier for users to install, update, and manage the application. + +| Package Manager | OS | Status | Directory | +|-----------------|-----|--------|-----------| +| **Chocolatey** | Windows | Supported | `build/chocolatey/` | +| **Homebrew** | macOS | Supported | `build/homebrew/` | +| **Winget** | Windows | Optional | Future | + +## Quick Start: Simplest Approach (Direct Distribution) + +**No infrastructure or accounts needed** - just build once and share: + +```powershell +# 1. Build the Chocolatey package +cd build/chocolatey +python ../../build/scripts/build_windows.py --msi +certutil -hashfile "../../build/dist/windows/WebDropBridge_Setup.msi" SHA256 +# Update checksum in tools/chocolateyInstall.ps1 +choco pack webdrop-bridge.nuspec + +# 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.0.8.0.nupkg -s "\\server\packages" +``` + +**Advantages:** +- ✅ No accounts or external infrastructure +- ✅ Works in air-gapped/offline environments +- ✅ Simple one-time setup +- ✅ Version management through file shares + +**For centralized distribution**, see Options 1-3 below. + +--- + +## Chocolatey (Windows) + +### Prerequisites + +- Chocolatey installed: https://chocolatey.org/install +- (Only for public community repo) Chocolatey maintainer account at chocolatey.org + +### Building the Chocolatey Package + +```bash +# 1. Build MSI installer first +python build/scripts/build_windows.py --msi + +# 2. Calculate SHA256 checksum of the MSI +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 +# 0.8.0 + +# 5. Create the package +cd build/chocolatey +choco pack webdrop-bridge.nuspec +``` + +This creates `webdrop-bridge.0.8.0.nupkg` + +### Publishing to Chocolatey + +**Option 1: Internal NuGet Repository (Recommended for HIM)** + +Host on your own NuGet server (Azure Artifacts, Artifactory, ProGet, etc.): + +```powershell +# Configure Chocolatey to use internal repository +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 + +# Users install from internal repo (already configured) +choco install webdrop-bridge +``` + +**Option 2: Community Repository (chocolatey.org)** + +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 +``` + +**Option 3: No Repository (Direct Distribution)** + +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 Installation + +Depending on your chosen distribution: + +```powershell +# If using internal repository +choco install webdrop-bridge + +# If using community repo (chocolatey.org) +choco install webdrop-bridge + +# If distributing directly +choco install webdrop-bridge.0.8.0.nupkg -s "\\network\share\packages" +``` + +## Homebrew (macOS) + +### Prerequisites + +- Homebrew installed: https://brew.sh +- GitHub or Gitea account for hosting tap repository + +### Two Approaches + +#### Option A: Local Tap (Recommended for HIM) + +Create a custom tap repository to distribute your formula without submitting to official Homebrew. + +**Setup:** + +```bash +# Create tap repository +mkdir homebrew-webdrop-bridge +cd homebrew-webdrop-bridge + +# Create structure +mkdir -p Formula +cp ../build/homebrew/webdrop-bridge.rb Formula/ + +# Initialize git repo and push to Forgejo +git init +git add . +git commit -m "Add webdrop-bridge formula" +git remote add origin https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git +git push -u origin main +``` + +**User Installation:** + +```bash +# Add tap +brew tap HIM-public/webdrop-bridge https://git.him-tools.de/HIM-public/homebrew-webdrop-bridge.git + +# Install +brew install webdrop-bridge + +# Upgrade +brew upgrade webdrop-bridge +``` + +#### Option B: Official Homebrew Repository + +Submit to `homebrew/casks` (requires more maintenance but no separate tap): + +1. Fork https://github.com/Homebrew/homebrew-casks +2. Create pull request with Cask file +3. Homebrew maintainers review and merge +4. Users install via `brew install --cask webdrop-bridge` + +### Building the Homebrew Package (Locally) + +```bash +# 1. Build DMG installer +bash build/scripts/build_macos.sh + +# 2. Calculate SHA256 checksum +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.X.X/WebDropBridge_Setup.dmg +# - sha256: YOUR_SHA256_HASH +``` + +### Testing Homebrew Formula Locally + +```bash +# Validate formula syntax +brew audit --formula build/homebrew/webdrop-bridge.rb + +# Install from local formula +brew install build/homebrew/webdrop-bridge.rb + +# Verify installation +brew list webdrop-bridge +webdrop-bridge --version # If CLI exists, or check Applications folder +``` + +## Publishing Workflow + +### Step 1: Build Release + +```bash +# Release v0.8.0 + +# Windows MSI +python build/scripts/build_windows.py --msi + +# macOS DMG +bash build/scripts/build_macos.sh +``` + +### Step 2: Create Forgejo Release + +Tag and upload installers to Forgejo: + +```bash +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 +``` + +### Step 3: Calculate Checksums + +```bash +# Windows +certutil -hashfile WebDropBridge_Setup.msi SHA256 + +# macOS +shasum -a 256 WebDropBridge_Setup.dmg +``` + +### Step 4: Update Package Manager Files + +**Chocolatey** (`build/chocolatey/tools/chocolateyInstall.ps1`): +```powershell +$Checksum = 'WINDOWS_SHA256_HASH' +``` + +**Homebrew** (`build/homebrew/webdrop-bridge.rb`): +```ruby +sha256 "MACOS_SHA256_HASH" +``` + +### Step 5: Test Package Installation + +**Chocolatey:** +```powershell +cd build/chocolatey +choco pack +choco install webdrop-bridge.0.8.0.nupkg -s . +``` + +**Homebrew (with tap):** +```bash +brew install ./build/homebrew/webdrop-bridge.rb +``` + +### Step 6: Publish + +**Chocolatey:** +```powershell +choco push webdrop-bridge.0.8.0.nupkg --api-key YOUR_KEY +``` + +**Homebrew:** +- If using local tap: Push to Forgejo repository +- If using official: Submit pull request to homebrew-casks + +## Update Workflow + +### For Subsequent Releases (e.g., v0.9.0) + +1. Build new installers (MSI/DMG) +2. Create Forgejo release with new version +3. Calculate new checksums +4. Update version and checksums in: + - `build/chocolatey/webdrop-bridge.nuspec` + - `build/chocolatey/tools/chocolateyInstall.ps1` + - `build/homebrew/webdrop-bridge.rb` +5. Test locally +6. Publish to package managers + +## Configuration in Package Managers + +### Chocolatey + +Located in: `build/chocolatey/tools/chocolateyInstall.ps1` + +Key variables to update per release: +- `$Version` - Application version +- `$Url` - Download URL (Forgejo release) +- `$Checksum` - SHA256 hash of MSI +- `$ChecksumType` - Type of hash (sha256) + +### Homebrew + +Located in: `build/homebrew/webdrop-bridge.rb` + +Key variables to update per release: +- `version` - Application version +- `url` - Download URL (Forgejo release) +- `sha256` - SHA256 hash of DMG + +## Automatic Updates + +### Via Package Managers + +When users install via Chocolatey/Homebrew, they receive updates through: + +```bash +# Chocolatey +choco upgrade webdrop-bridge + +# Homebrew +brew upgrade webdrop-bridge +``` + +### Built-in Auto-Update (Fallback) + +WebDropBridge also includes built-in auto-update mechanism that: +1. Checks Forgejo releases API on startup +2. Notifies user of available updates +3. Downloads and installs directly (bypasses package manager) + +This works for: +- Direct downloads via wget +- Standalone installer use +- Users who skip package manager route + +## Troubleshooting + +### Chocolatey Issues + +**Package won't install:** +- Verify checksum: `certutil -hashfile WebDropBridge_Setup.msi SHA256` +- Check MSI exists at URL: `wget URL` +- Verify SHA256 matches in `chocolateyInstall.ps1` + +**Uninstall fails:** +- Try manual uninstall first +- Then recreate the Chocolatey package + +### Homebrew Issues + +**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` + +**Upgrade fails:** +- Remove old version: `brew uninstall webdrop-bridge` +- Reinstall: `brew install webdrop-bridge` + +## References + +- **Chocolatey Documentation**: https://docs.chocolatey.org/ +- **Homebrew Formula Reference**: https://docs.brew.sh/Formula-Cookbook +- **Homebrew Cask**: https://docs.brew.sh/Cask-Cookbook +- **Forgejo Releases**: https://git.him-tools.de/HIM-public/webdrop-bridge/releases + +--- + +**Distribution Strategy Options for HIM:** + +1. **Easiest: Direct Distribution** ✅ + - Share `.nupkg` file via file share or email + - Users: `choco install webdrop-bridge.0.8.0.nupkg -s "\\share\packages"` + - No infrastructure needed + - No maintainer account required + +2. **Better: Internal NuGet Repository** ✅ (Recommended) + - Host on Azure Artifacts or Artifactory + - Professional package management + - Automatic updates with `choco upgrade` + - Users: `choco install webdrop-bridge` (pre-configured) + +3. **Public: Chocolatey Community** (Optional) + - Publish to chocolatey.org (requires maintainer account + vetting) + - Widest distribution + - Public users: `choco install webdrop-bridge`