aethex-forge/docs/DESKTOP-RELEASE.md

AeThex Desktop App - Release Guide

This guide covers building, signing, and distributing the AeThex Desktop application.

Quick Start

Prerequisites

• Node.js 20+
• npm or yarn
• For Windows builds: Windows 10/11
• For macOS builds: macOS 11+ with Xcode Command Line Tools
• For Linux builds: Ubuntu 20.04+ or equivalent

Building Locally

# Install dependencies
npm install

# Build the desktop app (creates installers in ./dist)
npm run desktop:build

Automated Builds (GitHub Actions)

The repository includes a GitHub Actions workflow that automatically builds for all platforms.

Triggering a Release

1. Tag a release:

   git tag v1.0.0
   git push origin v1.0.0
   

2. Manual trigger: Go to Actions > Build Desktop App > Run workflow

Build Artifacts

After a successful build, artifacts are available:

• Windows: AeThex Desktop Terminal-{version}-win-x64.exe
• macOS: AeThex Desktop Terminal-{version}-mac-{arch}.dmg
• Linux: AeThex Desktop Terminal-{version}-x64.AppImage, .deb

Code Signing

Windows Code Signing

To sign Windows builds, you need a code signing certificate.

1. Get a certificate:

   • Purchase from DigiCert, Sectigo, or other CA
   • Or use Azure SignTool with Azure Key Vault

2. Add GitHub Secrets:

   WIN_CSC_LINK: Base64-encoded .pfx certificate
   WIN_CSC_KEY_PASSWORD: Certificate password
   

3. Update electron-builder.yml:

   win:
     certificateFile: ${env.WIN_CSC_LINK}
     certificatePassword: ${env.WIN_CSC_KEY_PASSWORD}
   

macOS Code Signing & Notarization

Apple requires apps to be signed and notarized for distribution.

1. Prerequisites:

   • Apple Developer Program membership ($99/year)
   • Developer ID Application certificate
   • App-specific password for notarization

2. Add GitHub Secrets:

   APPLE_ID: Your Apple ID email
   APPLE_APP_SPECIFIC_PASSWORD: Generated from appleid.apple.com
   APPLE_TEAM_ID: Your Team ID (from Developer Portal)
   CSC_LINK: Base64-encoded .p12 certificate
   CSC_KEY_PASSWORD: Certificate password
   

3. Update GitHub workflow to include notarization:

   - name: Build and notarize
     run: npm run desktop:build
     env:
       APPLE_ID: ${{ secrets.APPLE_ID }}
       APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
       APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
       CSC_LINK: ${{ secrets.CSC_LINK }}
       CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
   

4. Update electron-builder.yml:

   mac:
     notarize:
       teamId: ${env.APPLE_TEAM_ID}
   

Auto-Updates

The app is configured to check for updates from GitHub Releases.

How it works:

1. User installs the app
2. On launch, app checks GitHub Releases for newer version
3. If found, prompts user to download and install

Configuration

The publish section in electron-builder.yml configures the update server:

publish:
  provider: github
  owner: aethex
  repo: aethex-desktop
  releaseType: release

Testing Updates

1. Build version 1.0.0 and install
2. Push version 1.0.1 to GitHub Releases
3. Launch the app - it should detect and offer the update

Customization

App Icons

Replace files in build/icons/:

• icon.ico - Windows (256x256 multi-size)
• icon.icns - macOS (512x512 multi-size)
• icon.png - Linux (512x512)

See build/icons/README.md for conversion instructions.

Installer Graphics

Windows NSIS:

• build/installerHeader.bmp - 150x57 pixels
• build/installerSidebar.bmp - 164x314 pixels

macOS DMG:

• build/icons/icon.icns - Volume icon
• (Optional) Add build/dmg-background.png (540x380 pixels) and update electron-builder.yml with dmg.background: build/dmg-background.png

License

Add a LICENSE file to the root directory to display during Windows installation.

Troubleshooting

"App is damaged" on macOS

• App is not signed or notarized
• Run: xattr -cr /Applications/AeThex\ Desktop\ Terminal.app

Windows SmartScreen warning

• App is not code-signed
• Users can click "More info" > "Run anyway"

Linux AppImage won't run

chmod +x AeThex*.AppImage
./AeThex*.AppImage

Build fails with "icon not found"

• Ensure build/icons/icon.ico exists for Windows builds
• Ensure build/icons/icon.icns exists for macOS builds

Version Management

Update version in package.json before creating a release tag:

{
  "version": "1.0.0"
}

The version is used in:

• Installer filename
• Auto-update checks
• About dialog