Windows Installer Workflows

Windows Installer Workflows

This document describes the GitHub Actions workflows for building Windows installers for the Krill platform. Two separate workflows are provided: one for the Krill Server and one for the Krill Desktop application.

Overview

The Windows installer workflows create MSI (Microsoft Installer) packages that can be distributed to Windows 11 users. These workflows follow similar patterns to the existing Debian packaging workflows but use Windows-native tooling.

Workflow	Application	Output Format	Runner
Build Windows Server	Krill Server	MSI	windows-latest
Build Windows Desktop	Krill Desktop	MSI	windows-latest

Architecture

graph TD
    A[Manual Trigger] --> B{Which Workflow?}
    B --> C[Build Windows Server]
    B --> D[Build Windows Desktop]
    
    C --> E[Build Server JAR]
    E --> F[Build WASM Archive]
    F --> G[Create WiX Config]
    G --> H[Build MSI with WiX]
    H --> I[Upload to S3]
    
    D --> J[Build Desktop via Gradle]
    J --> K[Package MSI via JPackage]
    K --> L[Upload to S3]

Workflow 1: Build Windows Server Installer

Purpose

Creates a Windows installer for the Krill Server application, including:

• The server JAR file
• WASM web application archive
• Launcher batch script
• Start menu shortcuts

Trigger

on:
  workflow_dispatch:  # Manual trigger only

Build Steps

1. Checkout & Setup
   • Checkout main branch
   • Set up JDK 21 (Temurin)
   • Configure Gradle
2. Build Artifacts
   • Build WASM archive using :composeApp:wasmZip
   • Build server JAR using :server:shadowJar
3. Prepare Installer Files
   • Create staging directory structure
   • Copy server JAR to bin/krill.jar
   • Copy WASM archive to wasm/
   • Generate launcher batch script
4. Create MSI Installer
   • Generate WiX configuration file
   • Install WiX Toolset 4
   • Build MSI package
5. Upload Artifacts
   • Upload versioned MSI to S3
   • Upload latest MSI to S3
   • Store as GitHub Actions artifact

Output Location

Installers are uploaded to S3:

• Versioned: s3://deb.krill.zone/windows/krill-server-{version}.msi
• Latest: s3://deb.krill.zone/windows/krill-server.msi

Download URL

https://deb.krill.zone/windows/krill-server.msi

Workflow 2: Build Windows Desktop Installer

Purpose

Creates a Windows installer for the Krill Desktop application using Compose Multiplatform’s native packaging capabilities.

Trigger

on:
  workflow_dispatch:  # Manual trigger only

Build Steps

1. Checkout & Setup
   • Checkout main branch
   • Set up JDK 21 (Temurin)
   • Configure Gradle
2. Build Desktop Application
   • Run :composeApp:packageReleaseMsi
   • Uses JPackage internally for native packaging
3. Organize Output
   • Find built MSI file
   • Copy with versioned name
   • Create latest version copy
4. Upload Artifacts
   • Upload versioned MSI to S3
   • Upload latest MSI to S3
   • Store as GitHub Actions artifact

Output Location

Installers are uploaded to S3:

• Versioned: s3://deb.krill.zone/windows/krill-desktop-{version}.msi
• Latest: s3://deb.krill.zone/windows/krill-desktop.msi

Download URL

https://deb.krill.zone/windows/krill-desktop.msi

Code Signing (TODO)

Both workflows include placeholder code for Windows code signing. Code signing is recommended for production releases to:

• Prevent Windows SmartScreen warnings
• Build user trust
• Enable Microsoft Store distribution
• Meet enterprise deployment requirements

Required Secrets

To enable code signing, configure these GitHub Secrets:

Secret	Description
WINDOWS_SIGNING_CERT_BASE64	Base64-encoded PFX certificate file
WINDOWS_SIGNING_CERT_PASSWORD	Password for the PFX file

Certificate Options

1. Standard Code Signing Certificate
   • Available from CAs like DigiCert, Sectigo, GlobalSign
   • Requires organization validation
   • Cost: ~$200-500/year
2. Extended Validation (EV) Certificate
   • Immediately trusted by Windows SmartScreen
   • Requires extended organization validation
   • Cost: ~$300-700/year
   • Recommended for wide distribution
3. Azure Key Vault Signing
   • Store certificates securely in Azure
   • Use Azure SignTool for signing
   • Best for enterprise deployments

Enabling Code Signing

Uncomment the signing steps in the workflow files and configure the required secrets:

- name: Sign MSI installer
  shell: pwsh
  env:
    SIGNING_CERT_BASE64: ${{ secrets.WINDOWS_SIGNING_CERT_BASE64 }}
    SIGNING_CERT_PASSWORD: ${{ secrets.WINDOWS_SIGNING_CERT_PASSWORD }}
  run: |
    # Signing commands...

Microsoft Store Distribution (TODO)

For Microsoft Store distribution, additional setup is required:

1. Register for Microsoft Partner Center
   • Create a developer account at partner.microsoft.com
   • One-time registration fee applies
2. App Certification
   • Pass Windows App Certification Kit (WACK) tests
   • Meet Microsoft Store policies
3. MSIX Packaging
   • Consider converting MSI to MSIX format
   • Better Store integration and auto-updates
4. Store Submission API
   • Configure API credentials for automated submissions
   • Use microsoft-store-submission-api GitHub Action

Gradle Configuration

The desktop packaging is configured in composeApp/build.gradle.kts:

compose {
    desktop {
        application {
            mainClass = "krill.zone.MainKt"
            nativeDistributions {
                targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
                packageName = "krill-desktop"
                packageVersion = "<version from version.txt>"  // Updated by Release The Kraken workflow
                vendor = "Krill"
                description = "Krill Desktop Control Application"
            }
        }
    }
}

Note: The packageVersion is automatically updated by the “Release The Kraken” workflow during releases.

Comparison with Other Platforms

Platform	Workflow	Package Format	Signing	Store
Windows Server	Build Windows Server	MSI	TODO	N/A
Windows Desktop	Build Windows Desktop	MSI	TODO	TODO
macOS	Build Mac Desktop	DMG	N/A	N/A
Linux	Deploy Debian Repo	DEB	GPG	N/A
Android	Deploy Android	AAB	Keystore	Google Play
iOS	Build iOS	XCFramework	TODO	TODO

Running the Workflows

Manual Trigger

1. Go to Actions tab in GitHub
2. Select the desired workflow:
   • “Build Windows Server Installer” or
   • “Build Windows Desktop Installer”
3. Click Run workflow
4. Select branch (main)
5. Click Run workflow button

Expected Duration

Workflow	Approximate Time
Build Windows Server	10-15 minutes
Build Windows Desktop	8-12 minutes

Troubleshooting

Common Issues

Build fails with missing JDK

• Ensure JDK 21 setup step completes successfully
• Check for network issues downloading Temurin

MSI not found after build

• Check Gradle output for errors
• Verify targetFormats includes Msi

S3 upload fails

• Verify AWS credentials are configured
• Check bucket permissions

WiX build fails

• Ensure WiX configuration is valid XML
• Check for special characters in version string

Debugging

Enable verbose logging:

- name: Build with debug output
  run: ./gradlew :composeApp:packageReleaseMsi --info --stacktrace

Future Enhancements

• Add code signing with EV certificate
• Configure Microsoft Store submission
• Add MSIX packaging option
• Include Windows Service wrapper for server
• Add unattended installation support
• Configure auto-update mechanism
• Add installer localization

Related Workflows

• Deploy Debian Repo: Linux DEB packaging
• Build Mac Desktop: macOS DMG packaging
• Deploy Android: Android AAB packaging
• Release The Kraken: Full platform release orchestration

Summary

The Windows installer workflows provide:

✅ Automated Builds: MSI creation via GitHub Actions
✅ S3 Distribution: Installers uploaded to S3 bucket
✅ Version Management: Both versioned and latest installers
✅ Artifact Retention: 30-day retention in GitHub Actions
⏳ Code Signing: Prepared but pending certificate setup
⏳ Store Distribution: Prepared for future Microsoft Store release

These workflows enable Windows users to easily install and run Krill applications with a familiar MSI installer experience.