diff --git a/.github/workflows/electron-build.yml b/.github/workflows/electron-build.yml index 288f8ee6..0b7c6285 100644 --- a/.github/workflows/electron-build.yml +++ b/.github/workflows/electron-build.yml @@ -653,6 +653,411 @@ jobs: path: choco-build/*.nupkg retention-days: 30 + submit-to-flatpak: + runs-on: ubuntu-latest + if: github.event.inputs.artifact_destination == 'submit' + needs: [build-linux] + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Get version from package.json + id: package-version + run: | + VERSION=$(node -p "require('./package.json').version") + RELEASE_DATE=$(date +%Y-%m-%d) + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "release_date=$RELEASE_DATE" >> $GITHUB_OUTPUT + echo "Building Flatpak submission for version: $VERSION" + + - name: Download Linux x64 AppImage artifact + uses: actions/download-artifact@v4 + with: + name: termix_linux_x64_appimage + path: artifact-x64 + + - name: Download Linux arm64 AppImage artifact + uses: actions/download-artifact@v4 + with: + name: termix_linux_arm64_appimage + path: artifact-arm64 + + - name: Get AppImage file info + id: appimage-info + run: | + VERSION="${{ steps.package-version.outputs.version }}" + + # x64 AppImage + APPIMAGE_X64_FILE=$(find artifact-x64 -name "*.AppImage" -type f | head -n 1) + APPIMAGE_X64_NAME=$(basename "$APPIMAGE_X64_FILE") + CHECKSUM_X64=$(sha256sum "$APPIMAGE_X64_FILE" | awk '{print $1}') + + # arm64 AppImage + APPIMAGE_ARM64_FILE=$(find artifact-arm64 -name "*.AppImage" -type f | head -n 1) + APPIMAGE_ARM64_NAME=$(basename "$APPIMAGE_ARM64_FILE") + CHECKSUM_ARM64=$(sha256sum "$APPIMAGE_ARM64_FILE" | awk '{print $1}') + + echo "appimage_x64_name=$APPIMAGE_X64_NAME" >> $GITHUB_OUTPUT + echo "checksum_x64=$CHECKSUM_X64" >> $GITHUB_OUTPUT + echo "appimage_arm64_name=$APPIMAGE_ARM64_NAME" >> $GITHUB_OUTPUT + echo "checksum_arm64=$CHECKSUM_ARM64" >> $GITHUB_OUTPUT + + echo "x64 AppImage: $APPIMAGE_X64_NAME" + echo "x64 SHA256: $CHECKSUM_X64" + echo "arm64 AppImage: $APPIMAGE_ARM64_NAME" + echo "arm64 SHA256: $CHECKSUM_ARM64" + + - name: Install ImageMagick for icon generation + run: | + sudo apt-get update + sudo apt-get install -y imagemagick + + - name: Prepare Flatpak submission files + run: | + VERSION="${{ steps.package-version.outputs.version }}" + CHECKSUM_X64="${{ steps.appimage-info.outputs.checksum_x64 }}" + CHECKSUM_ARM64="${{ steps.appimage-info.outputs.checksum_arm64 }}" + RELEASE_DATE="${{ steps.package-version.outputs.release_date }}" + APPIMAGE_X64_NAME="${{ steps.appimage-info.outputs.appimage_x64_name }}" + APPIMAGE_ARM64_NAME="${{ steps.appimage-info.outputs.appimage_arm64_name }}" + + # Create submission directory + mkdir -p flatpak-submission + + # Copy Flatpak files to submission directory + cp flatpak/com.karmaa.termix.yml flatpak-submission/ + cp flatpak/com.karmaa.termix.desktop flatpak-submission/ + cp flatpak/com.karmaa.termix.metainfo.xml flatpak-submission/ + cp flatpak/flathub.json flatpak-submission/ + + # Copy and prepare icons + cp public/icon.svg flatpak-submission/com.karmaa.termix.svg + convert public/icon.png -resize 256x256 flatpak-submission/icon-256.png + convert public/icon.png -resize 128x128 flatpak-submission/icon-128.png + + # Update manifest with version and checksums + sed -i "s/VERSION_PLACEHOLDER/$VERSION/g" flatpak-submission/com.karmaa.termix.yml + sed -i "s/CHECKSUM_X64_PLACEHOLDER/$CHECKSUM_X64/g" flatpak-submission/com.karmaa.termix.yml + sed -i "s/CHECKSUM_ARM64_PLACEHOLDER/$CHECKSUM_ARM64/g" flatpak-submission/com.karmaa.termix.yml + + # Update metainfo with version and date + sed -i "s/VERSION_PLACEHOLDER/$VERSION/g" flatpak-submission/com.karmaa.termix.metainfo.xml + sed -i "s/DATE_PLACEHOLDER/$RELEASE_DATE/g" flatpak-submission/com.karmaa.termix.metainfo.xml + + echo "✅ Flatpak submission files prepared for version $VERSION" + echo "x64 Download URL: https://github.com/Termix-SSH/Termix/releases/download/release-$VERSION-tag/$APPIMAGE_X64_NAME" + echo "arm64 Download URL: https://github.com/Termix-SSH/Termix/releases/download/release-$VERSION-tag/$APPIMAGE_ARM64_NAME" + + - name: Create submission instructions + run: | + cat > flatpak-submission/SUBMISSION_INSTRUCTIONS.md << 'EOF' + # Flathub Submission Instructions for Termix + + ## Automatic Submission (Recommended) + + All files needed for Flathub submission are in this artifact. Follow these steps: + + 1. **Fork the Flathub repository**: + - Go to https://github.com/flathub/flathub + - Click "Fork" button + + 2. **Clone your fork**: + ```bash + git clone https://github.com/YOUR-USERNAME/flathub.git + cd flathub + git checkout -b com.karmaa.termix + ``` + + 3. **Copy all files from this artifact** to the root of your flathub fork + + 4. **Commit and push**: + ```bash + git add . + git commit -m "Add Termix ${{ steps.package-version.outputs.version }}" + git push origin com.karmaa.termix + ``` + + 5. **Create Pull Request**: + - Go to https://github.com/YOUR-USERNAME/flathub + - Click "Compare & pull request" + - Submit PR to flathub/flathub + + ## Files in this submission: + + - `com.karmaa.termix.yml` - Flatpak manifest + - `com.karmaa.termix.desktop` - Desktop entry + - `com.karmaa.termix.metainfo.xml` - AppStream metadata + - `flathub.json` - Flathub configuration + - `com.karmaa.termix.svg` - SVG icon + - `icon-256.png` - 256x256 icon + - `icon-128.png` - 128x128 icon + + ## Version Information: + + - Version: ${{ steps.package-version.outputs.version }} + - Release Date: ${{ steps.package-version.outputs.release_date }} + - x64 AppImage SHA256: ${{ steps.appimage-info.outputs.checksum_x64 }} + - arm64 AppImage SHA256: ${{ steps.appimage-info.outputs.checksum_arm64 }} + + ## After Submission: + + 1. Flathub maintainers will review your submission (usually 1-5 days) + 2. They may request changes - be responsive to feedback + 3. Once approved, Termix will be available via: `flatpak install flathub com.karmaa.termix` + + ## Resources: + + - [Flathub Submission Guidelines](https://docs.flathub.org/docs/for-app-authors/submission) + - [Flatpak Documentation](https://docs.flatpak.org/) + EOF + + echo "✅ Created submission instructions" + + - name: List submission files + run: | + echo "Flatpak submission files:" + ls -la flatpak-submission/ + + - name: Upload Flatpak submission as artifact + uses: actions/upload-artifact@v4 + with: + name: flatpak-submission + path: flatpak-submission/* + retention-days: 30 + + - name: Display next steps + run: | + echo "" + echo "🎉 Flatpak submission files ready!" + echo "" + echo "📦 Download the 'flatpak-submission' artifact and follow SUBMISSION_INSTRUCTIONS.md" + echo "" + echo "Quick summary:" + echo "1. Fork https://github.com/flathub/flathub" + echo "2. Copy artifact files to your fork" + echo "3. Create PR to flathub/flathub" + echo "" + + submit-to-homebrew: + runs-on: macos-latest + if: github.event.inputs.artifact_destination == 'submit' + needs: [build-macos] + permissions: + contents: read + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Get version from package.json + id: package-version + run: | + VERSION=$(node -p "require('./package.json').version") + echo "version=$VERSION" >> $GITHUB_OUTPUT + echo "Building Homebrew Cask for version: $VERSION" + + - name: Download macOS Universal DMG artifact + uses: actions/download-artifact@v4 + with: + name: termix_macos_universal_dmg + path: artifact + + - name: Get DMG file info + id: dmg-info + run: | + VERSION="${{ steps.package-version.outputs.version }}" + DMG_FILE=$(find artifact -name "*.dmg" -type f | head -n 1) + DMG_NAME=$(basename "$DMG_FILE") + CHECKSUM=$(shasum -a 256 "$DMG_FILE" | awk '{print $1}') + + echo "dmg_name=$DMG_NAME" >> $GITHUB_OUTPUT + echo "checksum=$CHECKSUM" >> $GITHUB_OUTPUT + echo "DMG File: $DMG_NAME" + echo "SHA256: $CHECKSUM" + + - name: Prepare Homebrew submission files + run: | + VERSION="${{ steps.package-version.outputs.version }}" + CHECKSUM="${{ steps.dmg-info.outputs.checksum }}" + DMG_NAME="${{ steps.dmg-info.outputs.dmg_name }}" + + # Create submission directory + mkdir -p homebrew-submission/Casks/t + + # Copy Homebrew cask file + cp homebrew/termix.rb homebrew-submission/Casks/t/termix.rb + cp homebrew/README.md homebrew-submission/ + + # Update cask with version and checksum + sed -i '' "s/VERSION_PLACEHOLDER/$VERSION/g" homebrew-submission/Casks/t/termix.rb + sed -i '' "s/CHECKSUM_PLACEHOLDER/$CHECKSUM/g" homebrew-submission/Casks/t/termix.rb + + echo "✅ Homebrew Cask prepared for version $VERSION" + echo "Download URL: https://github.com/Termix-SSH/Termix/releases/download/release-$VERSION-tag/$DMG_NAME" + + - name: Verify Cask syntax + run: | + # Install Homebrew if not present (should be on macos-latest) + if ! command -v brew &> /dev/null; then + echo "Installing Homebrew..." + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + fi + + # Basic syntax check + ruby -c homebrew-submission/Casks/t/termix.rb + echo "✅ Cask syntax is valid" + + - name: Create submission instructions + run: | + cat > homebrew-submission/SUBMISSION_INSTRUCTIONS.md << 'EOF' + # Homebrew Cask Submission Instructions for Termix + + ## Option 1: Submit to Official Homebrew Cask (Recommended) + + ### Prerequisites + - macOS with Homebrew installed + - GitHub account + + ### Steps + + 1. **Fork the Homebrew Cask repository**: + - Go to https://github.com/Homebrew/homebrew-cask + - Click "Fork" button + + 2. **Clone your fork**: + ```bash + git clone https://github.com/YOUR-USERNAME/homebrew-cask.git + cd homebrew-cask + git checkout -b termix + ``` + + 3. **Copy the cask file**: + - Copy `Casks/t/termix.rb` from this artifact to your fork at `Casks/t/termix.rb` + - Note: Casks are organized by first letter in subdirectories + + 4. **Test the cask locally**: + ```bash + brew install --cask ./Casks/t/termix.rb + brew uninstall --cask termix + ``` + + 5. **Run audit checks**: + ```bash + brew audit --cask --online ./Casks/t/termix.rb + brew style ./Casks/t/termix.rb + ``` + + 6. **Commit and push**: + ```bash + git add Casks/t/termix.rb + git commit -m "Add Termix ${{ steps.package-version.outputs.version }}" + git push origin termix + ``` + + 7. **Create Pull Request**: + - Go to https://github.com/YOUR-USERNAME/homebrew-cask + - Click "Compare & pull request" + - Fill in the PR template + - Submit to Homebrew/homebrew-cask + + ### PR Requirements + + Your PR should include: + - Clear commit message: "Add Termix X.Y.Z" or "Update Termix to X.Y.Z" + - All audit checks passing + - Working download URL + - Valid SHA256 checksum + + ## Option 2: Create Your Own Tap (Alternative) + + If you want more control and faster updates: + + 1. **Create a tap repository**: + - Create repo: `Termix-SSH/homebrew-termix` + - Add `Casks/termix.rb` to the repo + + 2. **Users install with**: + ```bash + brew tap termix-ssh/termix + brew install --cask termix + ``` + + ### Advantages of Custom Tap + - No approval process + - Instant updates + - Full control + - Can include beta versions + + ### Disadvantages + - Less discoverable + - Users must add tap first + - You maintain it yourself + + ## Files in this submission: + + - `Casks/t/termix.rb` - Homebrew Cask formula + - `README.md` - Detailed documentation + - `SUBMISSION_INSTRUCTIONS.md` - This file + + ## Version Information: + + - Version: ${{ steps.package-version.outputs.version }} + - DMG SHA256: ${{ steps.dmg-info.outputs.checksum }} + - DMG URL: https://github.com/Termix-SSH/Termix/releases/download/release-${{ steps.package-version.outputs.version }}-tag/${{ steps.dmg-info.outputs.dmg_name }} + + ## After Submission: + + ### Official Homebrew Cask: + 1. Maintainers will review (usually 24-48 hours) + 2. May request changes or fixes + 3. Once merged, users can install with: `brew install --cask termix` + 4. Homebrew bot will auto-update for future releases + + ### Custom Tap: + 1. Push to your tap repository + 2. Immediately available to users + 3. Update the cask file for each new release + + ## Resources: + + - [Homebrew Cask Documentation](https://docs.brew.sh/Cask-Cookbook) + - [Acceptable Casks](https://docs.brew.sh/Acceptable-Casks) + - [How to Open a PR](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request) + EOF + + echo "✅ Created submission instructions" + + - name: List submission files + run: | + echo "Homebrew submission files:" + find homebrew-submission -type f + + - name: Upload Homebrew submission as artifact + uses: actions/upload-artifact@v4 + with: + name: homebrew-submission + path: homebrew-submission/* + retention-days: 30 + + - name: Display next steps + run: | + echo "" + echo "🍺 Homebrew Cask ready!" + echo "" + echo "📦 Download the 'homebrew-submission' artifact and follow SUBMISSION_INSTRUCTIONS.md" + echo "" + echo "Quick summary:" + echo "Option 1 (Recommended): Fork https://github.com/Homebrew/homebrew-cask and submit PR" + echo "Option 2 (Alternative): Create your own tap at Termix-SSH/homebrew-termix" + echo "" + upload-to-release: runs-on: blacksmith-4vcpu-ubuntu-2404 if: github.event.inputs.artifact_destination == 'release' diff --git a/PACKAGE_MANAGERS.md b/PACKAGE_MANAGERS.md new file mode 100644 index 00000000..7140eab8 --- /dev/null +++ b/PACKAGE_MANAGERS.md @@ -0,0 +1,362 @@ +# Package Manager Submissions for Termix + +This document describes the package manager integrations for Termix and how to use them. + +## Chocolatey (Windows) + +### Overview + +Chocolatey package files are located in the `chocolatey/` directory. + +### Files + +- `termix.nuspec` - Package manifest +- `tools/chocolateyinstall.ps1` - Installation script +- `tools/chocolateyuninstall.ps1` - Uninstallation script + +### Automatic Submission + +When you run the "Build Electron App" workflow with `artifact_destination: submit`: + +1. The workflow builds the Windows x64 MSI +2. Automatically creates a Chocolatey package +3. Pushes to Chocolatey if `CHOCOLATEY_API_KEY` secret is configured + +### Setup + +Add your Chocolatey API key as a GitHub secret: + +- Secret name: `CHOCOLATEY_API_KEY` +- Get your API key from: https://community.chocolatey.org/account + +### Manual Submission + +If you prefer to submit manually: + +1. Download the `chocolatey-package` artifact from GitHub Actions +2. Run: `choco push termix.{VERSION}.nupkg --source https://push.chocolatey.org/` + +### Installation (for users) + +Once approved on Chocolatey: + +```powershell +choco install termix +``` + +--- + +## Flatpak (Linux) + +### Overview + +Flatpak package files are located in the `flatpak/` directory. + +### Files + +- `com.karmaa.termix.yml` - Flatpak manifest (supports x64 and arm64) +- `com.karmaa.termix.desktop` - Desktop entry file +- `com.karmaa.termix.metainfo.xml` - AppStream metadata +- `flathub.json` - Flathub configuration +- `prepare-flatpak.sh` - Helper script for manual preparation +- `README.md` - Detailed Flatpak documentation + +### Automatic Preparation + +When you run the "Build Electron App" workflow with `artifact_destination: submit`: + +1. The workflow builds Linux x64 and arm64 AppImages +2. Generates all required Flatpak submission files +3. Creates a `flatpak-submission` artifact with everything needed + +### Submission Process + +Flatpak requires manual PR submission to Flathub: + +1. **Download the artifact** + - Download `flatpak-submission` from the GitHub Actions run + - Extract all files + +2. **Fork Flathub** + - Go to https://github.com/flathub/flathub + - Click "Fork" + +3. **Prepare your fork** + + ```bash + git clone https://github.com/YOUR-USERNAME/flathub.git + cd flathub + git checkout -b com.karmaa.termix + ``` + +4. **Copy submission files** + - Copy all files from the `flatpak-submission` artifact to your fork root + +5. **Submit PR** + + ```bash + git add . + git commit -m "Add Termix application" + git push origin com.karmaa.termix + ``` + + - Go to your fork on GitHub + - Click "Compare & pull request" + - Submit to flathub/flathub + +6. **Wait for review** + - Flathub maintainers will review (typically 1-5 days) + - Be responsive to feedback + +### Testing Locally + +Before submitting, you can test the Flatpak build: + +```bash +# Install flatpak-builder +sudo apt install flatpak-builder + +# Build and install +cd flatpak/ +flatpak-builder --user --install --force-clean build-dir com.karmaa.termix.yml + +# Run +flatpak run com.karmaa.termix +``` + +### Installation (for users) + +Once approved on Flathub: + +```bash +flatpak install flathub com.karmaa.termix +``` + +--- + +## Homebrew Cask (macOS) + +### Overview + +Homebrew Cask files are located in the `homebrew/` directory. Casks are used for GUI macOS applications. + +### Files + +- `termix.rb` - Homebrew Cask formula +- `README.md` - Detailed documentation + +### Submission Options + +You have two options for distributing via Homebrew: + +#### Option 1: Official Homebrew Cask (Recommended) + +Submit to https://github.com/Homebrew/homebrew-cask for maximum visibility. + +**Advantages:** + +- Discoverable by all Homebrew users +- Automatic update checking +- Official Homebrew support + +**Process:** + +1. Download the `homebrew-submission` artifact from GitHub Actions +2. Fork Homebrew/homebrew-cask +3. Add the cask file to `Casks/t/termix.rb` +4. Test locally and run audit checks +5. Submit PR + +**Requirements:** + +- App must be stable (not beta) +- Source code must be public +- Must pass `brew audit --cask` checks +- DMG must be code-signed and notarized (already done) + +#### Option 2: Custom Tap (Alternative) + +Create your own Homebrew tap at `Termix-SSH/homebrew-termix`. + +**Advantages:** + +- Full control over updates +- No approval process +- Can include beta releases + +**Setup:** + +```bash +# Create repository: Termix-SSH/homebrew-termix +# Add file: Casks/termix.rb (from homebrew-submission artifact) +``` + +**Users install with:** + +```bash +brew tap termix-ssh/termix +brew install --cask termix +``` + +### Automatic Preparation + +When you run the "Build Electron App" workflow with `artifact_destination: submit`: + +1. Builds macOS universal DMG +2. Calculates SHA256 checksum +3. Updates cask file with version and checksum +4. Verifies Ruby syntax +5. Creates a `homebrew-submission` artifact + +### Installation (for users) + +**From Official Homebrew (after approval):** + +```bash +brew install --cask termix +``` + +**From Custom Tap:** + +```bash +brew tap termix-ssh/termix +brew install --cask termix +``` + +### Updating the Cask + +**Official Homebrew Cask:** + +- Homebrew bot auto-updates within hours of new releases +- Or manually submit PR with new version/checksum + +**Custom Tap:** + +- Update version and sha256 in termix.rb +- Commit to your tap repository +- Users run: `brew upgrade --cask termix` + +### Testing Locally + +```bash +# Test installation +brew install --cask ./homebrew/termix.rb + +# Verify it works +open /Applications/Termix.app + +# Uninstall +brew uninstall --cask termix + +# Run audit +brew audit --cask --online ./homebrew/termix.rb +brew style ./homebrew/termix.rb +``` + +--- + +## Workflow Integration + +### GitHub Actions Workflow + +The `.github/workflows/electron-build.yml` includes three package manager submission jobs: + +1. **submit-to-chocolatey** - Automatically submits to Chocolatey + - Requires: `CHOCOLATEY_API_KEY` secret + - Runs when: `artifact_destination == 'submit'` + - Platform: Windows + - Output: Auto-pushes to Chocolatey + artifact + +2. **submit-to-flatpak** - Prepares Flatpak submission files + - No secrets required + - Runs when: `artifact_destination == 'submit'` + - Platform: Linux + - Output: Artifact for manual Flathub PR (both x64 and arm64) + +3. **submit-to-homebrew** - Prepares Homebrew Cask submission files + - No secrets required + - Runs when: `artifact_destination == 'submit'` + - Platform: macOS + - Output: Artifact for manual Homebrew PR or custom tap + +### Usage + +When creating a release, select "submit" for artifact destination: + +- This will build for all platforms (Windows, Linux, macOS) +- Automatically submit to Chocolatey (if API key is configured) +- Create Flatpak submission artifact for manual Flathub PR +- Create Homebrew submission artifact for manual Homebrew PR or custom tap + +### Artifacts Generated + +- `chocolatey-package` - .nupkg file (also auto-pushed if key configured) +- `flatpak-submission` - Complete Flathub submission (x64 + arm64) +- `homebrew-submission` - Complete Homebrew Cask submission (universal DMG) + +--- + +## Version Management + +Both package managers automatically use the version from `package.json`: + +- Current version: 1.8.0 +- Version is dynamically injected during the build process +- Download URLs are constructed using the release tag format: `release-{VERSION}-tag` + +### Important Notes + +- Ensure your GitHub releases follow the tag format: `release-X.Y.Z-tag` +- Example: `release-1.8.0-tag` +- If your tag format differs, update the workflows accordingly + +--- + +## Support + +For issues with: + +- **Chocolatey package**: Open issue at https://community.chocolatey.org/packages/termix +- **Flatpak package**: Open issue at https://github.com/flathub/com.karmaa.termix +- **Homebrew Cask**: + - Official: Open issue at https://github.com/Homebrew/homebrew-cask/issues + - Custom tap: Open issue in your tap repository +- **Build process**: Open issue at https://github.com/Termix-SSH/Termix/issues + +## Installation Summary + +### Windows + +```powershell +# Chocolatey (after approval) +choco install termix +``` + +### Linux + +```bash +# Flatpak (after approval) +flatpak install flathub com.karmaa.termix +``` + +### macOS + +```bash +# Official Homebrew Cask (after approval) +brew install --cask termix + +# Or from custom tap +brew tap termix-ssh/termix +brew install --cask termix +``` + +--- + +## Future Package Managers + +To add support for additional package managers: + +1. Create a directory with package files (e.g., `snap/`, `homebrew/`) +2. Add a job to `.github/workflows/electron-build.yml` +3. Update this document with instructions +4. Consider whether submission can be automated or requires manual PR diff --git a/PACKAGE_SUBMISSION_SUMMARY.md b/PACKAGE_SUBMISSION_SUMMARY.md new file mode 100644 index 00000000..cd6ed35f --- /dev/null +++ b/PACKAGE_SUBMISSION_SUMMARY.md @@ -0,0 +1,309 @@ +# Package Submission Setup Summary + +This document summarizes all the package manager integrations that have been set up for Termix. + +## Overview + +Termix now has complete package manager support for all three major platforms: + +- **Windows**: Chocolatey +- **Linux**: Flatpak (Flathub) +- **macOS**: Homebrew Cask + +## Files Created + +### Chocolatey (Windows) + +``` +chocolatey/ +├── termix.nuspec # Package manifest +└── tools/ + ├── chocolateyinstall.ps1 # Installation script + └── chocolateyuninstall.ps1 # Uninstallation script +``` + +### Flatpak (Linux) + +``` +flatpak/ +├── com.karmaa.termix.yml # Flatpak manifest (x64 & arm64) +├── com.karmaa.termix.desktop # Desktop entry file +├── com.karmaa.termix.metainfo.xml # AppStream metadata +├── flathub.json # Flathub configuration +├── prepare-flatpak.sh # Helper script +└── README.md # Detailed documentation +``` + +### Homebrew (macOS) + +``` +homebrew/ +├── termix.rb # Homebrew Cask formula +└── README.md # Detailed documentation +``` + +### Documentation + +``` +PACKAGE_MANAGERS.md # Complete guide for all package managers +PACKAGE_SUBMISSION_SUMMARY.md # This file +``` + +### Modified Files + +``` +.github/workflows/electron-build.yml # Added 3 new submission jobs +``` + +## GitHub Actions Integration + +### New Jobs Added to Workflow + +1. **submit-to-chocolatey** (Lines 551-654) + - Platform: Windows + - Trigger: `artifact_destination == 'submit'` + - Actions: + - Downloads Windows x64 MSI + - Calculates SHA256 checksum + - Updates package manifest with version/checksum + - Packs Chocolatey package + - Automatically pushes to Chocolatey (if API key configured) + - Creates artifact for backup + +2. **submit-to-flatpak** (Lines 656-844) + - Platform: Linux (Ubuntu) + - Trigger: `artifact_destination == 'submit'` + - Actions: + - Downloads x64 and arm64 AppImages + - Calculates SHA256 checksums for both architectures + - Generates PNG icons from SVG + - Updates manifest and metainfo with version/checksums/date + - Creates complete submission artifact + - Includes detailed submission instructions + +3. **submit-to-homebrew** (Lines 846-1059) + - Platform: macOS + - Trigger: `artifact_destination == 'submit'` + - Actions: + - Downloads macOS universal DMG + - Calculates SHA256 checksum + - Updates Cask formula with version/checksum + - Verifies Ruby syntax + - Creates submission artifact + - Includes instructions for both official and custom tap + +## Setup Required + +### Chocolatey (Automated) + +Add GitHub secret to enable automatic submission: + +- **Secret name**: `CHOCOLATEY_API_KEY` +- **Get from**: https://community.chocolatey.org/account +- **Location**: Repository Settings → Secrets and variables → Actions + +### Flatpak (Manual) + +No secrets required. Process: + +1. Run workflow with "submit" option +2. Download `flatpak-submission` artifact +3. Fork https://github.com/flathub/flathub +4. Copy files and create PR + +### Homebrew (Manual) + +No secrets required. Two options: + +**Option 1: Official Homebrew** + +1. Run workflow with "submit" option +2. Download `homebrew-submission` artifact +3. Fork https://github.com/Homebrew/homebrew-cask +4. Add to `Casks/t/termix.rb` and create PR + +**Option 2: Custom Tap** + +1. Create repository: `Termix-SSH/homebrew-termix` +2. Add `Casks/termix.rb` from artifact +3. Users install with: `brew tap termix-ssh/termix && brew install --cask termix` + +## How to Use + +### For Each Release: + +1. **Prepare Release** + - Ensure version in `package.json` is updated + - Create GitHub release with tag format: `release-X.Y.Z-tag` + - Example: `release-1.8.0-tag` + +2. **Run Build Workflow** + - Go to Actions → "Build Electron App" + - Click "Run workflow" + - Select options: + - **Platform**: `all` (or specific platform) + - **Artifact destination**: `submit` + +3. **Automated Submissions** + - **Chocolatey**: Automatically pushed (if API key configured) + - Package appears on Chocolatey within hours + - Users can install with: `choco install termix` + +4. **Manual Submissions** + - **Flatpak**: Download `flatpak-submission` artifact + - Follow instructions in `SUBMISSION_INSTRUCTIONS.md` + - Submit PR to flathub/flathub + - Review time: 1-5 days + + - **Homebrew**: Download `homebrew-submission` artifact + - Follow instructions in `SUBMISSION_INSTRUCTIONS.md` + - Option 1: Submit PR to Homebrew/homebrew-cask + - Option 2: Push to custom tap + - Review time (official): 24-48 hours + +## Version Management + +All package managers automatically use the version from `package.json`: + +- Current version: **1.8.0** +- Version format: Semantic versioning (X.Y.Z) +- All checksums calculated automatically +- Download URLs constructed automatically + +## Important Notes + +### Release Tag Format + +The workflows expect GitHub release tags in this format: + +``` +release-{VERSION}-tag +``` + +Examples: + +- ✅ `release-1.8.0-tag` +- ✅ `release-2.0.0-tag` +- ❌ `v1.8.0` +- ❌ `1.8.0` + +If your tag format is different, update these lines in the workflows: + +- **Chocolatey**: Line 597 +- **Flatpak**: Lines 724-725 +- **Homebrew**: Line 900 + +### Code Signing Requirements + +All builds require proper code signing: + +- **Windows MSI**: Already signed via electron-builder +- **Linux AppImage**: No signing required +- **macOS DMG**: Must be signed and notarized (already configured) + +### File Naming Conventions + +The workflows expect these file naming patterns: + +- Windows: `termix_windows_x64_{version}_msi.msi` +- Linux x64: `termix_linux_x64_{version}_appimage.AppImage` +- Linux arm64: `termix_linux_arm64_{version}_appimage.AppImage` +- macOS: `termix_macos_universal_{version}_dmg.dmg` + +These are already configured in `electron-builder.json`. + +## Testing Locally + +### Chocolatey + +```powershell +cd chocolatey +choco pack termix.nuspec +choco install termix -s . -y +``` + +### Flatpak + +```bash +cd flatpak +flatpak-builder --user --install --force-clean build-dir com.karmaa.termix.yml +flatpak run com.karmaa.termix +``` + +### Homebrew + +```bash +cd homebrew +brew install --cask ./termix.rb +brew uninstall --cask termix +``` + +## User Installation Commands + +Once approved on all platforms: + +```bash +# Windows (Chocolatey) +choco install termix + +# Linux (Flatpak) +flatpak install flathub com.karmaa.termix + +# macOS (Homebrew - Official) +brew install --cask termix + +# macOS (Homebrew - Custom Tap) +brew tap termix-ssh/termix +brew install --cask termix +``` + +## Update Strategy + +### Chocolatey + +- Updates pushed automatically when you run workflow with "submit" +- Users update with: `choco upgrade termix` + +### Flatpak + +- After initial approval, you get a repository: `flathub/com.karmaa.termix` +- For updates: commit new version/checksum to that repo +- Flathub auto-builds and publishes +- Users update with: `flatpak update` + +### Homebrew (Official) + +- Homebrew bot auto-updates within hours of new releases +- Detects new releases via GitHub releases +- Users update with: `brew upgrade --cask termix` + +### Homebrew (Custom Tap) + +- Manually update the cask file in your tap repo +- Users update with: `brew upgrade --cask termix` + +## Resources + +- [Chocolatey Documentation](https://docs.chocolatey.org/) +- [Flatpak Documentation](https://docs.flatpak.org/) +- [Flathub Submission](https://docs.flathub.org/docs/for-app-authors/submission) +- [Homebrew Cask Cookbook](https://docs.brew.sh/Cask-Cookbook) +- [AppStream Guidelines](https://www.freedesktop.org/software/appstream/docs/) + +## Support + +For issues: + +- **Build/Workflow**: https://github.com/Termix-SSH/Termix/issues +- **Chocolatey**: https://community.chocolatey.org/packages/termix +- **Flatpak**: https://github.com/flathub/com.karmaa.termix/issues +- **Homebrew**: https://github.com/Homebrew/homebrew-cask/issues (or your custom tap) + +--- + +**Next Steps:** + +1. Add `CHOCOLATEY_API_KEY` to GitHub secrets +2. Run workflow with "submit" option for your next release +3. Download artifacts and follow submission instructions +4. Monitor submission PRs and respond to feedback diff --git a/flatpak/com.karmaa.termix.desktop b/flatpak/com.karmaa.termix.desktop new file mode 100644 index 00000000..3aabfd06 --- /dev/null +++ b/flatpak/com.karmaa.termix.desktop @@ -0,0 +1,11 @@ +[Desktop Entry] +Name=Termix +Comment=Web-based server management platform with SSH terminal, tunneling, and file editing +Exec=termix %U +Icon=com.karmaa.termix +Terminal=false +Type=Application +Categories=Development;Network;System; +Keywords=ssh;terminal;server;management;tunnel; +StartupWMClass=termix +StartupNotify=true diff --git a/flatpak/com.karmaa.termix.metainfo.xml b/flatpak/com.karmaa.termix.metainfo.xml new file mode 100644 index 00000000..0c3c6895 --- /dev/null +++ b/flatpak/com.karmaa.termix.metainfo.xml @@ -0,0 +1,77 @@ + + + com.karmaa.termix + Termix + Web-based server management platform with SSH terminal, tunneling, and file editing + + CC0-1.0 + GPL-3.0-or-later + + bugattiguy527 + + +

+ Termix is an open-source, forever-free, self-hosted all-in-one server management platform. + It provides a web-based solution for managing your servers and infrastructure through a single, intuitive interface. +

+

Features:

+ +
+ + com.karmaa.termix.desktop + + + + https://raw.githubusercontent.com/Termix-SSH/Termix/main/public/screenshots/terminal.png + SSH Terminal Interface + + + + https://github.com/Termix-SSH/Termix + https://github.com/Termix-SSH/Support/issues + https://docs.termix.site + https://github.com/Termix-SSH/Termix + + + moderate + + + + + +

Latest release of Termix

+
+ https://github.com/Termix-SSH/Termix/releases +
+
+ + + Development + Network + System + + + + ssh + terminal + server + management + tunnel + file-manager + + + + termix + + + + always + +
diff --git a/flatpak/com.karmaa.termix.yml b/flatpak/com.karmaa.termix.yml new file mode 100644 index 00000000..ce4091e5 --- /dev/null +++ b/flatpak/com.karmaa.termix.yml @@ -0,0 +1,69 @@ +app-id: com.karmaa.termix +runtime: org.freedesktop.Platform +runtime-version: '23.08' +sdk: org.freedesktop.Sdk +base: org.electronjs.Electron2.BaseApp +base-version: '23.08' +command: termix +separate-locales: false + +finish-args: + - --socket=x11 + - --socket=wayland + - --socket=pulseaudio + - --share=network + - --share=ipc + - --device=dri + - --filesystem=home + - --socket=ssh-auth + - --talk-name=org.freedesktop.Notifications + - --talk-name=org.freedesktop.secrets + +modules: + - name: termix + buildsystem: simple + build-commands: + - chmod +x termix.AppImage + - ./termix.AppImage --appimage-extract + + - install -Dm755 squashfs-root/termix /app/bin/termix + - cp -r squashfs-root/resources /app/bin/ + - cp -r squashfs-root/locales /app/bin/ || true + + - install -Dm644 com.karmaa.termix.desktop /app/share/applications/com.karmaa.termix.desktop + + - install -Dm644 com.karmaa.termix.metainfo.xml /app/share/metainfo/com.karmaa.termix.metainfo.xml + + - install -Dm644 com.karmaa.termix.svg /app/share/icons/hicolor/scalable/apps/com.karmaa.termix.svg + - install -Dm644 icon-256.png /app/share/icons/hicolor/256x256/apps/com.karmaa.termix.png || true + - install -Dm644 icon-128.png /app/share/icons/hicolor/128x128/apps/com.karmaa.termix.png || true + + sources: + - type: file + url: https://github.com/Termix-SSH/Termix/releases/download/release-VERSION_PLACEHOLDER-tag/termix_linux_x64_VERSION_PLACEHOLDER_appimage.AppImage + sha256: CHECKSUM_X64_PLACEHOLDER + dest-filename: termix.AppImage + only-arches: + - x86_64 + + - type: file + url: https://github.com/Termix-SSH/Termix/releases/download/release-VERSION_PLACEHOLDER-tag/termix_linux_arm64_VERSION_PLACEHOLDER_appimage.AppImage + sha256: CHECKSUM_ARM64_PLACEHOLDER + dest-filename: termix.AppImage + only-arches: + - aarch64 + + - type: file + path: com.karmaa.termix.desktop + + - type: file + path: com.karmaa.termix.metainfo.xml + + - type: file + path: com.karmaa.termix.svg + + - type: file + path: icon-256.png + + - type: file + path: icon-128.png diff --git a/flatpak/flathub.json b/flatpak/flathub.json new file mode 100644 index 00000000..43c4074e --- /dev/null +++ b/flatpak/flathub.json @@ -0,0 +1,5 @@ +{ + "only-arches": ["x86_64", "aarch64"], + "skip-icons-check": false, + "skip-appstream-check": false +} diff --git a/flatpak/prepare-flatpak.sh b/flatpak/prepare-flatpak.sh new file mode 100644 index 00000000..43afe818 --- /dev/null +++ b/flatpak/prepare-flatpak.sh @@ -0,0 +1,54 @@ +#!/bin/bash +set -e + +# This script prepares the Flatpak submission files +# It should be run from the repository root + +VERSION="$1" +CHECKSUM="$2" +RELEASE_DATE="$3" + +if [ -z "$VERSION" ] || [ -z "$CHECKSUM" ] || [ -z "$RELEASE_DATE" ]; then + echo "Usage: $0 " + echo "Example: $0 1.8.0 abc123... 2025-10-26" + exit 1 +fi + +echo "Preparing Flatpak submission for version $VERSION" + +# Copy icon files +cp public/icon.svg flatpak/com.karmaa.termix.svg +echo "✓ Copied SVG icon" + +# Generate PNG icons if ImageMagick is available +if command -v convert &> /dev/null; then + convert public/icon.png -resize 256x256 flatpak/icon-256.png + convert public/icon.png -resize 128x128 flatpak/icon-128.png + echo "✓ Generated PNG icons" +else + # Fallback: just copy the original PNG + cp public/icon.png flatpak/icon-256.png + cp public/icon.png flatpak/icon-128.png + echo "⚠ ImageMagick not found, using original icon" +fi + +# Update manifest with version and checksum +sed -i "s/VERSION_PLACEHOLDER/$VERSION/g" flatpak/com.karmaa.termix.yml +sed -i "s/CHECKSUM_PLACEHOLDER/$CHECKSUM/g" flatpak/com.karmaa.termix.yml +echo "✓ Updated manifest with version $VERSION" + +# Update metainfo with version and date +sed -i "s/VERSION_PLACEHOLDER/$VERSION/g" flatpak/com.karmaa.termix.metainfo.xml +sed -i "s/DATE_PLACEHOLDER/$RELEASE_DATE/g" flatpak/com.karmaa.termix.metainfo.xml +echo "✓ Updated metainfo with version $VERSION and date $RELEASE_DATE" + +echo "" +echo "✅ Flatpak submission files prepared!" +echo "" +echo "Next steps:" +echo "1. Review the files in the flatpak/ directory" +echo "2. Fork https://github.com/flathub/flathub" +echo "3. Create a new branch named 'com.karmaa.termix'" +echo "4. Copy all files from flatpak/ to the root of your fork" +echo "5. Commit and push to your fork" +echo "6. Open a PR to flathub/flathub" diff --git a/homebrew/README.md b/homebrew/README.md new file mode 100644 index 00000000..08b0f68f --- /dev/null +++ b/homebrew/README.md @@ -0,0 +1,154 @@ +# Homebrew Cask for Termix + +This directory contains the Homebrew Cask formula for installing Termix on macOS. + +## Files + +- **termix.rb** - Homebrew Cask formula + +## What is a Homebrew Cask? + +Homebrew Casks are used to install GUI macOS applications. Unlike formulae (which are for command-line tools), casks handle: + +- Downloading DMG/PKG installers +- Installing .app bundles to /Applications +- Managing application preferences and cache cleanup + +## Submission Options + +You have two options for distributing Termix via Homebrew: + +### Option 1: Submit to Official Homebrew Cask (Recommended) + +Submit to the official homebrew-cask repository for maximum visibility. + +**Advantages:** + +- Discoverable by all Homebrew users +- Built-in update checking +- Official Homebrew support + +**Process:** + +1. Download the `homebrew-submission` artifact from GitHub Actions (when using "submit" option) +2. Fork https://github.com/Homebrew/homebrew-cask +3. Create a new branch: `git checkout -b termix` +4. Add the cask file: `Casks/t/termix.rb` (note the subdirectory by first letter) +5. Test locally: `brew install --cask ./Casks/t/termix.rb` +6. Run audit: `brew audit --cask --online ./Casks/t/termix.rb` +7. Commit and push to your fork +8. Create a PR to Homebrew/homebrew-cask + +**Requirements for acceptance:** + +- App must be stable (not beta/alpha) +- Source code must be public +- No analytics/tracking without opt-in +- Pass all brew audit checks + +### Option 2: Create Your Own Tap + +Create a custom Homebrew tap for more control and faster updates. + +**Advantages:** + +- Full control over updates +- No approval process +- Can include beta/alpha releases + +**Process:** + +1. Create a new repository: `Termix-SSH/homebrew-termix` +2. Add the cask file to: `Casks/termix.rb` +3. Users install with: `brew install --cask termix-ssh/termix/termix` + +## Installation (for users) + +### From Official Homebrew Cask (after approval): + +```bash +brew install --cask termix +``` + +### From Custom Tap: + +```bash +# Add the tap +brew tap termix-ssh/termix + +# Install the cask +brew install --cask termix +``` + +## Updating the Cask + +When you release a new version: + +### For Official Homebrew Cask: + +1. Homebrew bot usually auto-updates within hours +2. Or manually submit a PR with the new version/checksum + +### For Custom Tap: + +1. Update the version and sha256 in termix.rb +2. Commit and push to your tap repository +3. Users run: `brew upgrade --cask termix` + +## Testing Locally + +Before submitting, test the cask: + +```bash +# Install from local file +brew install --cask ./homebrew/termix.rb + +# Verify it works +open /Applications/Termix.app + +# Uninstall +brew uninstall --cask termix + +# Run audit checks +brew audit --cask --online ./homebrew/termix.rb + +# Style check +brew style ./homebrew/termix.rb +``` + +## Automated Submission Preparation + +The GitHub Actions workflow automatically prepares the Homebrew submission when you select "submit": + +1. Builds macOS universal DMG +2. Calculates SHA256 checksum +3. Updates the cask file with version and checksum +4. Creates a `homebrew-submission` artifact + +Download the artifact and follow the submission instructions included. + +## Cask File Structure + +The cask file (`termix.rb`) includes: + +- **version** - Automatically set from package.json +- **sha256** - Checksum of the universal DMG for security +- **url** - Download URL from GitHub releases +- **name** - Display name +- **desc** - Short description +- **homepage** - Project homepage +- **livecheck** - Automatic update detection +- **app** - The .app bundle to install +- **zap** - Files to remove on complete uninstall + +## Requirements + +- macOS 10.15 (Catalina) or later +- Homebrew 4.0.0 or later +- Universal DMG must be code-signed and notarized (already handled by your build process) + +## Resources + +- [Homebrew Cask Documentation](https://docs.brew.sh/Cask-Cookbook) +- [Cask Submission Guidelines](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md) +- [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook) diff --git a/homebrew/termix.rb b/homebrew/termix.rb new file mode 100644 index 00000000..9522fa73 --- /dev/null +++ b/homebrew/termix.rb @@ -0,0 +1,24 @@ +cask "termix" do + version "VERSION_PLACEHOLDER" + sha256 "CHECKSUM_PLACEHOLDER" + + url "https://github.com/Termix-SSH/Termix/releases/download/release-#{version}-tag/termix_macos_universal_#{version}_dmg.dmg" + name "Termix" + desc "Web-based server management platform with SSH terminal, tunneling, and file editing" + homepage "https://github.com/Termix-SSH/Termix" + + livecheck do + url :url + strategy :github_latest + end + + app "Termix.app" + + zap trash: [ + "~/Library/Application Support/termix", + "~/Library/Caches/com.karmaa.termix", + "~/Library/Caches/com.karmaa.termix.ShipIt", + "~/Library/Preferences/com.karmaa.termix.plist", + "~/Library/Saved Application State/com.karmaa.termix.savedState", + ] +end