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:

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

```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`