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