webdrop-bridge/docs/PACKAGE_MANAGER_SUPPORT.md

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:

# 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

# 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
#    <version>0.8.0</version>

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

# 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):

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

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

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

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

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

# 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

# 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

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

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

# 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):

$Checksum = 'WINDOWS_SHA256_HASH'

Homebrew (build/homebrew/webdrop-bridge.rb):

sha256 "MACOS_SHA256_HASH"

Step 5: Test Package Installation

Chocolatey:

cd build/chocolatey
choco pack
choco install webdrop-bridge.0.8.0.nupkg -s .

Homebrew (with tap):

brew install ./build/homebrew/webdrop-bridge.rb

Step 6: Publish

Chocolatey:

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:

# 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