# How to Upgrade Apache Maka: Complete Guide for Desktop and CLI

> Upgrade Apache Maka with this comprehensive guide. Learn the staged approach to backup, validate binaries, and migrate your SQLite schema seamlessly.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Upgrading Apache Maka requires a staged approach that backs up the existing installation, validates the new binary against a baseline manifest, and automatically migrates the SQLite schema while preserving workspace state.**

Apache Maka is an open-source workspace management platform that distributes both desktop installers and command-line interfaces. Whether you are upgrading the Windows desktop application or the npm-based CLI, following the repository's official upgrade pipeline ensures atomic transitions without data loss.

## Desktop (Windows) Upgrade Process

The Windows installer implements a defensive upgrade strategy that creates a complete backup before modifying system files. According to the source code in `scripts/verify-windows-installer-rollback.mjs`, the installer generates a `<install-dir>.pre-upgrade-backup` directory (see line 46) and captures the current registry snapshot before proceeding.

### Baseline Validation

The upgrade pipeline validates every new build against a pinned baseline defined in [`scripts/windows-upgrade-baseline.json`](https://github.com/apache/maka/blob/main/scripts/windows-upgrade-baseline.json). This JSON manifest locks the exact Git tag, asset name, and SHA-256 hash of the approved release, preventing installation of corrupted or tampered binaries.

During installation, the process executes the verification logic found in `scripts/verify-windows-autoupdate.mjs` (lines 107-119), which confirms that the new binary reports the expected `currentVersion` before allowing the replacement to complete.

### Automated Rollback Protection

If the upgrade fails, the system automatically restores the pre-upgrade state. The rollback script (`scripts/verify-windows-installer-rollback.mjs`, lines 155-206) handles restoration of both files and registry entries. 

Critical safety check: if the backup directory remains after a successful upgrade, lines 321-324 of the rollback script abort the process and alert the user. This guarantees that stray backup folders never persist on production systems.

## CLI and npm Upgrade Method

The CLI distribution requires a different approach than standard npm packages. The official guidance in [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md) (line 126) explicitly warns against running `npm update --global maka-agent` because the `latest` tag is mutable and may point to incompatible pre-release builds.

### Targeted Version Installation

Use explicit version tags to ensure reproducible upgrades:

```bash

# Upgrade to the newest stable release

npm install -g @apache/maka@stable

# Or pin to a specific version

npm install -g @apache/maka@2.5.0

```

### Post-Upgrade Verification

After installation, validate the upgrade with built-in diagnostics:

```bash
maka --version           # Displays the installed version

maka db verify           # Executes internal schema-compatibility checks

```

## SQLite Schema Migration

Apache Maka stores all workspace data in `runtime.sqlite`. Schema migrations occur automatically when the new binary first accesses the database. The migration implementation in [`packages/storage/src/sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-schema.ts) (line 884) uses a **single write transaction** to serialize upgrades, ensuring that only one process modifies the schema at a time.

If a migration fails mid-process, the Windows installer's rollback logic restores the `runtime.sqlite` file from the pre-upgrade backup, returning the database to its original schema version without manual intervention.

## End-to-End Windows Upgrade Example

For Windows administrators performing manual upgrades, follow this PowerShell workflow that mirrors the automated pipeline:

```powershell

# Download the signed installer

Invoke-WebRequest -Uri "https://downloads.maka.apache.org/maka-2.5.0-windows-x64.exe" -OutFile "maka-installer.exe"

# Execute silent installation (automatically handles backup and validation)

.\maka-installer.exe /silent

# Verify the upgrade via the desktop API

$version = (Get-Item "C:\Program Files\Maka\maka.exe").VersionInfo.ProductVersion
Write-Host "Apache Maka upgraded to version $version"

```

The installer validates the binary using `window.maka.app.updateStatus()` (referenced in `scripts/verify-windows-autoupdate.mjs`, lines 421-473) to confirm the application launches correctly before finalizing the installation.

## Cross-Platform and Source Upgrades

On macOS and Linux, use the npm-based upgrade method described above. For developers building from source, pull the latest changes and rebuild the native dependencies:

```bash
git pull origin main
npm ci
npm run dev:peer           # For peer-enabled builds

# Or: npm run dev:full:peer

```

## Summary

- **Backup First**: The Windows installer automatically creates a `<install-dir>.pre-upgrade-backup` directory before modifying any files.
- **Validate Baseline**: Every upgrade checks against [`scripts/windows-upgrade-baseline.json`](https://github.com/apache/maka/blob/main/scripts/windows-upgrade-baseline.json) to verify binary integrity.
- **Avoid Latest Tags**: Use `npm install -g @apache/maka@stable` rather than mutable `latest` tags.
- **Atomic Migrations**: SQLite schema updates run inside serialized transactions at [`packages/storage/src/sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-schema.ts) line 884.
- **Automatic Recovery**: Failed Windows upgrades trigger rollback logic in `scripts/verify-windows-installer-rollback.mjs` to restore the previous state.

## Frequently Asked Questions

### What happens if the Windows upgrade is interrupted?

The installer maintains the pre-upgrade backup until the new binary successfully reports its version via the validation logic in `scripts/verify-windows-autoupdate.mjs`. If the process terminates early, the rollback script (lines 155-206 of `scripts/verify-windows-installer-rollback.mjs`) automatically restores the original installation directory and registry settings.

### Can I downgrade Apache Maka after upgrading?

Yes, provided the pre-upgrade backup directory still exists. Run the verification logic manually or reinstall the previous version over the current installation. The SQLite schema will revert to the backup copy if the rollback mechanism triggers. Never delete the `.pre-upgrade-backup` folder until you confirm the new version works correctly.

### Why does `npm update` fail for the CLI package?

The maintainers explicitly disable the `latest` tag for automatic updates (see [`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md) line 126). This prevents npm from installing potentially incompatible builds. Always specify either `@stable` or an exact version number when upgrading the global CLI package.

### How do I verify the installer file integrity?

The Windows installer validates itself against [`scripts/windows-upgrade-baseline.json`](https://github.com/apache/maka/blob/main/scripts/windows-upgrade-baseline.json), which contains the SHA-256 hash of the official release asset. Before running the installer manually, compare your downloaded file's checksum against the manifest published in the Apache Maka repository.