webdrop-bridge/FORGEJO_PACKAGES_SETUP.md

# Forgejo Packages Distribution Guide

This guide explains how to distribute WebDrop Bridge builds using **Forgejo Packages** instead of runners.

## Overview

**Forgejo Packages** is a package repository system that lets you upload and distribute binaries. It's simpler than setting up CI/CD runners and works perfectly for manual releases.

```
1. Build locally (Windows & macOS)
2. Upload exe + dmg to Forgejo Packages
3. UpdateManager downloads from Packages
4. Users verify with SHA256 checksums
```

## Setup Requirements

### 1. Use Your Existing Forgejo Credentials

You already have HTTP access to Forgejo. Just use the same username and password you use to log in.

Set environment variables with your Forgejo credentials:

**Windows (PowerShell):**
```powershell
$env:FORGEJO_USER = "your_forgejo_username"
$env:FORGEJO_PASS = "your_forgejo_password"
```

**macOS/Linux:**
```bash
export FORGEJO_USER="your_forgejo_username"
export FORGEJO_PASS="your_forgejo_password"
```

### 2. Build Scripts

Upload scripts are already created:
- Windows: `build/scripts/upload_to_packages.ps1`
- macOS: `build/scripts/upload_to_packages.sh`

## Release Workflow

### Step 1: Build Executables

**On Windows:**
```powershell
cd C:\Development\VS Code Projects\webdrop_bridge
python build/scripts/build_windows.py
# Output: build/dist/windows/WebDropBridge.exe
#         build/dist/windows/WebDropBridge.exe.sha256
```

**On macOS:**
```bash
cd ~/webdrop_bridge
bash build/scripts/build_macos.sh
# Output: build/dist/macos/WebDropBridge.dmg
#         build/dist/macos/WebDropBridge.dmg.sha256
```

### Step 2: Upload to Packages

After setting your environment variables (see Setup Requirements above), uploading is simple:

**Windows Upload:**
```powershell
$env:FORGEJO_USER = "your_username"
$env:FORGEJO_PASS = "your_password"
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0
```

**macOS Upload:**
```bash
export FORGEJO_USER="your_username"
export FORGEJO_PASS="your_password"
bash build/scripts/upload_to_packages.sh -v 1.0.0
```

Or set the environment variables once and they persist for all future uploads in that terminal session.

### Step 3: Tag and Commit

Once both are uploaded:
```bash
git tag -a v1.0.0 -m "Release version 1.0.0"
git push upstream v1.0.0
```

## Forgejo Packages API

### Package Structure

```
https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages
```

### Get Latest Version

```bash
curl https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages
```

Response:
```json
[
  {
    "id": 123,
    "name": "webdrop-bridge",
    "version": "1.0.0",
    "created_at": "2026-01-28T...",
    "files": [
      {
        "name": "WebDropBridge.exe",
        "size": 204840960,
        "file_name": "WebDropBridge.exe",
        "id": 456
      },
      {
        "name": "WebDropBridge.exe.sha256",
        "size": 65,
        "file_name": "WebDropBridge.exe.sha256",
        "id": 457
      }
    ]
  }
]
```

### Download URL

```
https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe
```

### Direct Package Page

```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

## UpdateManager Integration (Phase 4.1)

The auto-update system will query the Packages API:

```python
async def check_for_updates(self) -> Optional[UpdateInfo]:
    """Query Forgejo Packages for new version."""
    url = "https://git.him-tools.de/api/v1/repos/HIM-public/webdrop-bridge/packages"
    response = await session.get(url)
    packages = response.json()
    
    # Get latest package
    latest = packages[0]  # Sorted by date
    latest_version = latest['version']
    
    # Compare versions
    if parse_version(latest_version) > parse_version(self.current_version):
        return UpdateInfo(
            version=latest_version,
            download_url=f".../{latest_version}/WebDropBridge.exe",
            checksum_url=f".../{latest_version}/WebDropBridge.exe.sha256"
        )
    
    return None
```

## Upload Script Details

### Windows Script (`upload_to_packages.ps1`)

**Basic Usage:**
```powershell
# Set your Forgejo credentials
$env:FORGEJO_USER = "your_username"
$env:FORGEJO_PASS = "your_password"

# Upload
.\build\scripts\upload_to_packages.ps1 -Version 1.0.0
```

**Parameters:**
- `-Version` - Version number (required, e.g., "1.0.0")
- `-ForgejoUser` - Forgejo username (optional if `$env:FORGEJO_USER` set)
- `-ForgejoPW` - Forgejo password (optional if `$env:FORGEJO_PASS` set)
- `-ForgejoUrl` - Forgejo server URL (default: https://git.him-tools.de)
- `-Repo` - Repository (default: HIM-public/webdrop-bridge)
- `-ExePath` - Path to exe file (default: build\dist\windows\WebDropBridge.exe)
- `-ChecksumPath` - Path to checksum file

**Script flow:**
1. Check for credentials in: parameter → environment variables
2. Verify exe and checksum files exist
3. Upload exe to Packages API with HTTP Basic Auth
4. Upload checksum to Packages API
5. Show success message with package URL

### macOS Script (`upload_to_packages.sh`)

**Basic Usage:**
```bash
# Set your Forgejo credentials
export FORGEJO_USER="your_username"
export FORGEJO_PASS="your_password"

# Upload
bash build/scripts/upload_to_packages.sh -v 1.0.0
```

**Options:**
- `-v, --version` - Version number (required, e.g., "1.0.0")
- `-u, --url` - Forgejo server URL (default: https://git.him-tools.de)

**Script flow:**
1. Check for credentials in: environment variables (`$FORGEJO_USER`, `$FORGEJO_PASS`)
2. Verify dmg and checksum files exist
3. Upload dmg to Packages API with HTTP Basic Auth
4. Upload checksum to Packages API
5. Show success message with package URL

### Credential Resolution

Both scripts use HTTP Basic Authentication with your Forgejo username/password:
- Same credentials you use to log into Forgejo
- Same credentials git uses when cloning over HTTPS
- No special token creation needed

## Complete Release Checklist

```
[ ] Update version in src/webdrop_bridge/config.py
[ ] Update CHANGELOG.md with release notes
[ ] Build Windows executable
[ ] Verify WebDropBridge.exe exists
[ ] Verify WebDropBridge.exe.sha256 exists
[ ] Build macOS DMG
[ ] Verify WebDropBridge.dmg exists
[ ] Verify WebDropBridge.dmg.sha256 exists
[ ] Upload Windows to Packages
[ ] Upload macOS to Packages
[ ] Verify both on Packages page
[ ] Create git tag: git tag -a v1.0.0
[ ] Push tag: git push upstream v1.0.0
[ ] Announce release
```

## Troubleshooting

### Upload fails with "401 Unauthorized"

- Verify token is correct
- Check token has `write:package` scope
- Token may have expired - create new one

### Upload fails with "404 Not Found"

- Verify repository name is correct (`HIM-public/webdrop-bridge`)
- Verify version format (e.g., `1.0.0`, not `v1.0.0`)

### Checksum verification fails

- Regenerate checksums:
  ```powershell
  # Windows
  $file = "build\dist\windows\WebDropBridge.exe"
  $hash = (Get-FileHash -Path $file -Algorithm SHA256).Hash
  $hash | Out-File -FilePath "${file}.sha256" -NoNewline
  ```
  
  ```bash
  # macOS
  shasum -a 256 build/dist/macos/WebDropBridge.dmg > build/dist/macos/WebDropBridge.dmg.sha256
  ```

- Upload again

### Where are my packages?

View all uploads at:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

Each version shows:
- Files (exe/dmg + checksums)
- Upload date
- Download links

## Manual Download

Users can download directly:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.exe
https://git.him-tools.de/HIM-public/webdrop-bridge/packages/generic/webdrop-bridge/1.0.0/WebDropBridge.dmg
```

Or via Packages page UI:
```
https://git.him-tools.de/HIM-public/webdrop-bridge/packages
```

## Benefits of Packages

✅ **Simple**: No CI/CD runners needed  
✅ **Flexible**: Build when you want  
✅ **Reliable**: Forgejo handles storage  
✅ **Secure**: Token-based auth  
✅ **Integrated**: UpdateManager ready  
✅ **Free**: Built-in to Forgejo  

---

**Status**: Ready to use  
**Last Updated**: January 2026