feat: implement package manager support for Windows and macOS, including Chocolatey and Homebrew configurations
Some checks are pending
Tests & Quality Checks / Test on Python 3.11 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.10 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-2 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-2 (push) Waiting to run
Tests & Quality Checks / Build Artifacts (push) Blocked by required conditions
Tests & Quality Checks / Build Artifacts-1 (push) Blocked by required conditions
Some checks are pending
Tests & Quality Checks / Test on Python 3.11 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.10 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-2 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-2 (push) Waiting to run
Tests & Quality Checks / Build Artifacts (push) Blocked by required conditions
Tests & Quality Checks / Build Artifacts-1 (push) Blocked by required conditions
This commit is contained in:
parent
1dcce081f1
commit
87884935c9
9 changed files with 758 additions and 10 deletions
391
docs/PACKAGE_MANAGER_SUPPORT.md
Normal file
391
docs/PACKAGE_MANAGER_SUPPORT.md
Normal file
|
|
@ -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
|
||||
# <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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue