Application Packaging for Cross-Platform Distribution

[ecorkran]

Implement cross-platform packaging and distribution for Context Builder as native desktop application on macOS, Windows, and Linux.

Overview

Enable users to install and run Context Builder as a native desktop application without requiring development environment setup. Provide professional installation experience across all major desktop platforms.

User Value

• Install as native desktop application on macOS, Windows, and Linux
• No development environment or build tools required
• Professional installation experience with proper platform integration

Success Criteria

Primary Success Criteria

• macOS Distribution: DMG installer with proper code signing and notarization
• Windows Distribution: NSIS installer with code signing for Windows 10/11
• Linux Distribution: AppImage, deb, and rpm packages (no snap)
• Automated Builds: CI/CD pipeline generates all platform packages
• Installation Verification: Each package installs and launches successfully on target platforms

Secondary Success Criteria

• Professional Branding: Custom icons, splash screens, and installer branding
• Auto-Updates: Update mechanism for seamless version upgrades
• Digital Signatures: All packages signed for security and trust
• Release Management: Versioned releases with changelogs and assets

Implementation Phases

Phase 1: Enhanced Build Configuration (Effort: 2/5)

• Extend electron-builder configuration with comprehensive platform targets
• Configure Linux packaging formats: tar.xz, AppImage, deb, rpm
• Set up app metadata (descriptions, categories, desktop entries)
• Build unsigned packages for macOS and Windows (establishes process)

Phase 2: Asset and Branding Integration (Effort: 2/5)

• Design application icons for all platforms (icns, ico, png sets)
• Create installer background images and splash screens
• Configure metadata and desktop entries for each platform

Phase 3: Linux Package Signing (Effort: 1/5)

• Generate GPG key pair for package signing (free)
• Publish public key to keyservers
• Configure electron-builder for automatic GPG signing

Phase 4: Code Signing Setup (Effort: 3/5) - Future Phase

• Apple Developer Program membership and certificates (when org ready)
• Windows code signing certificate (after business verification)
• Configure automated signing and notarization workflows

Phase 5: CI/CD Pipeline Implementation (Effort: 4/5)

• GitHub Actions multi-platform build matrix
• Automated version tagging and release creation
• Package integrity verification and testing

Phase 6: Distribution and Auto-Update (Effort: 3/5)

• GitHub Releases for primary distribution
• Integrate electron-updater for seamless updates
• Update notification UI

Platform-Specific Details

macOS

• Format: DMG disk image with drag-to-Applications workflow
• Architecture: Universal binary (x64 + arm64)
• Code Signing: Developer certificate + notarization (future)
• Category: Developer Tools

Windows

• Format: NSIS installer with modern UI
• Architecture: x64 for Windows 10/11
• Code Signing: Authenticode certificate (future)
• Integration: Start menu shortcuts, file associations

Linux

• AppImage: Portable, universal format (no installation required)
• Debian/Ubuntu: .deb packages for apt-based distributions
• Red Hat/Fedora: .rpm packages for yum/dnf-based distributions
• Archive: .tar.xz for manual installation
• No Snap: Explicitly avoiding snap packages

Dependencies

Upstream Dependencies

• All core features completed and stable
• Application functionality production-ready
• Testing infrastructure in place

Build Tools

• electron-builder for packaging
• GitHub Actions for CI/CD
• Platform-specific build environments

Technical Notes

Technology Choices:

• electron-builder chosen for comprehensive platform support
• AppImage preferred over snap for Linux portability
• NSIS preferred over MSI for Windows customization

Distribution Strategy:

• Primary: GitHub Releases for direct distribution
• Secondary: Future package manager distribution (Homebrew, Chocolatey, etc.)

Code Signing Economics:

• Apple Developer Program: $99/year (when org ready)
• Windows Code Signing: ~$200-400/year (when org ready)
• Linux GPG Signing: Free (can implement immediately)

Business Setup Requirements (Future)

For proper organizational certificates (8 weeks before commercial release):

1. Business Registration (Week 1)
2. DUNS Number Application (Week 2)
3. Apple Developer Program (Week 3-4)
4. Windows Code Signing Certificate (Week 4-5)
5. Cloud/SaaS Startup Programs (Week 5-8)

Implementation Strategy:

• Start with unsigned builds to establish packaging process
• Add Linux GPG signing immediately (free, builds trust)
• Add commercial certificates when organizational setup complete

Design Reference

See project-documents/private/slices/125-slice.application-packaging.md for complete technical architecture and implementation details.