Application Updates

Audience: System Admin, Deployment Administrator, Developer Related: Packaged Distribution · Raspberry Pi · GCP · Environment and Secrets · Migrations

Package-managed Blackcap installations can discover, prepare, and apply approved Blackcap releases from System → Blackcap Updates. The Microwave Pie software delivery and instance management service remains authoritative for remote candidate selection. Blackcap never browses a package list or lets the browser supply an arbitrary package URL.

Version and provenance

Every new source or compiled package installs explicit build provenance even when .git is absent:

• Blackcap application version;
• numeric Git Version (git rev-list --count for the exact resolved package commit);
• exact full Git SHA for internal identity and health verification;
• Package and Release references;
• immutable deployment mode and platform;
• packaged database migration boundary.

About and ordinary user-facing version surfaces show the application version plus the conventional first seven characters of the exact full SHA, for example v0.6.565-alpha (7354cf6). The full 40-character SHA remains the authoritative technical provenance used for ancestry, package eligibility, Microwave Pie management-service reporting, audit, and exact post-update health validation. Legacy packages that do not contain a SHA continue to show only the application version; Blackcap never invents a SHA. Git Version remains display/provenance metadata and is never used as a substitute for Git ancestry.

Automatic and manual checks

The Microwave Pie management service calculates the normalized update decision during every accepted Blackcap instance heartbeat and returns it in the heartbeat response. Blackcap consumes that result immediately, so update availability follows the normal application-status reporting cadence with no separate time-based suppression window and no second automatic candidate request. When an approved newer release is available, Blackcap surfaces the shared Update Available state in the application UI, including the System update panel/header notification. This is a notification only: Blackcap does not force the update, automatically prepare it, automatically download it, or restart itself. A System Admin decides when to proceed and can choose Check for Updates at any time for an explicit live refresh.

Checking may report:

• current / no action;
• Update Available;
• Downgrade Recommended when the Microwave Pie management service's approved Git boundary/target is behind the installed source;
• Microwave Pie management service unavailable.

Discovery never downloads, stages, restarts, or downgrades Blackcap. The passive status contract exposes heartbeat-driven discovery through its backward-compatible automatic_check object (mode=heartbeat) and the latest persisted candidate. API Tester registers both the read-only Blackcap Update Status endpoint and the confirmed Check for Latest Blackcap Update action so the current target can be verified without relying on the System page UI.

Prepare Update

A System Admin explicitly chooses Prepare Update (or Prepare Recommended Downgrade when the Microwave Pie management service returns an approved older target). Preparation runs in the background while the current Blackcap release remains active. The System page stays open, shows the persisted server-side phase/progress, and polls a read-only passive status endpoint. That polling does not count as user activity for the inactivity timeout. Closing the browser or navigating away does not cancel preparation; returning later resumes from the persisted state. It:

1. refreshes the Microwave Pie management service's single approved candidate;
2. confirms the installation has package provenance;
3. checks free disk capacity for staging and rollback safety;
4. downloads server-to-server with the installed instance credential;
5. verifies the Microwave Pie management service's SHA-256 for the complete customer ZIP;
6. rejects unsafe ZIP paths, absolute paths, links, and special files;
7. verifies the Microwave Pie signed package manifest;
8. validates Blackcap application identity, existing Package identity, platform, immutable deployment mode, exact SHA, Git Version, Release reference, and package schema;
9. validates the packaged migration boundary for a downgrade;
10. stages the package under the protected updater state directory.

A prepared package is revalidated immediately before Apply. If the Microwave Pie management service closes, revokes, replaces, or otherwise makes that target ineligible, Apply is refused and the administrator must prepare again. When preparation reaches Ready, the page changes automatically to Apply Update and Restart Blackcap without a manual refresh. Preparation never automatically deploys or restarts Blackcap.

Apply Update

Apply Update always requires an explicit System Admin confirmation. Blackcap performs a fresh restart-impact check at confirmation time. Active Regression Tests, backup/restore, running background work, or other repository-defined blocking activity prevents restart; active Let's Cook sessions and queued work are shown as advisories where interruption is safe but noticeable.

The Package is not reported as newly installed merely because Apply was requested or because files were copied. The host updater must finish activation/health validation and mark the operation complete, and the restarted Blackcap process must confirm that its runtime distribution metadata contains the exact prepared Application Release and full Git SHA. Only then does Blackcap immediately acknowledge the installed release to the Microwave Pie management service using the existing authenticated Instance token and the exact Package/Download/release/manifest provenance. The acknowledgement is safe to retry, and Blackcap makes a few bounded post-start attempts without turning a successful application update into a failure if the Microwave Pie management service is temporarily unavailable. The normal instance heartbeat remains the eventual-consistency fallback.

On a successful acknowledgement, the Microwave Pie management service can therefore move the Package/Instance installed provenance to the new release immediately after restart instead of waiting for the next health ping. A mismatched running release/SHA is never acknowledged as installed.

The Flask/Gunicorn process does not replace itself. It writes one narrow update request that is consumed by the package-installed systemd updater. A healthy package-managed installation has blackcap-update.path both enabled and active; the package installer verifies that state as root before it reports the service-enablement stage complete. The System page also attempts a live systemctl query from the restricted Blackcap service account. If that live query is unavailable but the root-installed updater executable, unit files, and enablement link are intact, Blackcap reports Updater ready; live status unverified instead of incorrectly claiming that the unit is inactive. A definitive live inactive, failed, disabled, or masked state still blocks Prepare/Apply. The independent updater:

1. serves an Nginx-owned maintenance page;
2. stops Blackcap;
3. runs the already verified staged package installer;
4. runs normal idempotent database migrations through the service startup contract;
5. starts Blackcap;
6. waits for health;
7. verifies the running Release, full SHA, Git Version, and deployment mode exactly;
8. marks the new release current only after those checks pass.

The normal command-line package installer still asks whether to reuse an existing PostgreSQL configuration. A UI-triggered package update uses the already validated protected installation configuration and does not pause the independent updater waiting for interactive input.

Previous known-good version

Package-managed installations retain exactly the active release plus the immediately previous healthy release in steady state when a previous release is available:

/opt/blackcap/current   -> active immutable release
/opt/blackcap/previous  -> previous known-good immutable release

The previous slot is rotated only after the new release passes health and exact provenance verification. During an active update or restore a third release may be retained temporarily as a crash-recovery journal target, but terminal reconciliation removes stale releases so steady state returns to Current + Previous. Cleanup resolves and validates the current and previous symlink targets and never deletes outside /opt/blackcap/releases. If the new release fails, the rollback safety state is not discarded.

Restore Previous Version is a separate deliberate System Admin operation. It remains locally available even after the Microwave Pie management service's old generated package artifact has expired. Blackcap validates local metadata, platform/deployment mode, exact files, and database migration compatibility before restart. Microwave Pie management-service availability is not required merely to restore a legitimate locally retained release under the existing offline licensing rules.

A local previous release and a management-service downgrade recommendation are separate signals. The local release is still shown as a rollback choice even when the Microwave Pie management service recommends a different older target; Blackcap must not claim that restoring one version satisfies a Microwave Pie approved-release boundary when it does not.

Database downgrade safety

Blackcap does not generically reverse migrations. A prior application may have run successfully before a later update yet be unsafe against today's database schema. When the installed migration boundary is newer than the target package's known boundary, deliberate downgrade/restore is blocked unless compatibility can be proven by the package/update contract. Backup/restore remains the data-safety mechanism when a future update explicitly requires a pre-update database checkpoint.

A previous release can be physically retained but still be disabled for Restore Previous Version when its legacy metadata does not contain a migration boundary. Blackcap treats missing downgrade-compatibility provenance as unknown and refuses to guess. After a successful provenance-aware package update, subsequent previous slots carry the exact migration boundary needed for this preflight.

Failure and recovery

During activation, Nginx serves a friendly maintenance response instead of exposing a normal raw upstream 502. The updater records status under /var/lib/blackcap/updates/ and logs host activity to /var/lib/blackcap/updates/updater.log.

If activation fails after Blackcap stops, the updater restores the pre-update current release where the migration boundary makes that safe. A failed target is never treated as current and never replaces the previous known-good slot. On updater startup, an interrupted apply/restore is reconciled before stale-release cleanup so crash leftovers cannot cause the current or rollback target to be deleted.

If System → Blackcap Updates reports that the path unit is installed but inactive/disabled, repair the host unit before preparing an update:

sudo systemctl daemon-reload
sudo systemctl enable --now blackcap-update.path
sudo systemctl status blackcap-update.path --no-pager -l

A current package installer treats failure to enable/start this unit as an installation error instead of silently leaving UI updates unavailable.

Source and compiled deployments

Deployment mode is immutable through this UI workflow:

• source installation → source packages only;
• compiled installation → compiled packages only.

Source packages install the same explicit provenance and immutable release wrapper, so they do not depend on .git after installation. Compiled updates remain precompiled and do not require a compiler on the destination.

Package-managed source installations

A Source / uncompiled package is still package-managed application code. Its versioned release under /opt/blackcap/releases/ is treated as immutable just like a compiled release. Local edits made directly inside the active release are not merged into a later package and must not be relied on as persistent customization. Put supported configuration and persistent state in the existing /etc/blackcap and /var/lib/blackcap locations instead. Preparation never overwrites the running source release; a new immutable release is staged and only becomes current after explicit Apply.

For ordinary developer-managed changes outside a package-managed installation, the traditional reviewed-file deployment remains available, but production package-managed customer updates should use the package workflow rather than git pull, git checkout, or git reset --hard.

Header notification and manual inspection

For System Admins, the shared Admin header uses the same persisted update state as the System page. It shows Update Available when an approved forward target is known, Update Ready after preparation succeeds, and an in-progress state while an explicitly confirmed apply/restore is running. Org Admins and normal users do not receive this indicator.

Safe host inspection commands do not require database edits:

readlink -f /opt/blackcap/current
readlink -f /opt/blackcap/previous 2>/dev/null || true
ls -lah /opt/blackcap/releases
sudo cat /var/lib/blackcap/blackcap-distribution.json
sudo cat /var/lib/blackcap/previous-distribution.json 2>/dev/null || true
sudo cat /var/lib/blackcap/updates/state.json 2>/dev/null || true
sudo systemctl status blackcap-update.path blackcap-update.service --no-pager -l
sudo tail -n 120 /var/lib/blackcap/updates/updater.log

Do not manually remove release directories unless Current/Previous targets and updater state have first been validated.

Compiled Stats for Geeks build metrics

Compiled AMD64 builds record build-time Python LOC and UI LOC in immutable package provenance, calculated from the Blackcap source tree before compilation. Python LOC counts physical .py lines; UI LOC counts physical .html, .css, and .js lines using the same build exclusions. Stats for Geeks therefore reports comparable Python/UI code size for source and compiled deployments without exposing Nuitka-generated C/C++ volume. Legacy compiled packages may still provide the older sourcePythonLoc field, which is accepted as a Python LOC fallback; UI LOC is shown as not recorded when the older package did not capture it.

Release notes

System → Blackcap Updates provides View Release Notes as an informational link to Blackcap's canonical release-note documentation. The link is independent of update eligibility, package verification, Prepare, Apply, rollback, and offline runtime behavior. If public documentation is temporarily unreachable, an otherwise valid update remains available.

Microwave Pie package/release provenance uses a stable documentation reference (deployment/release-notes.md) rather than a temporary signed package URL. Blackcap accepts only its canonical release-notes document when resolving this reference, so Microwave Pie management-service data cannot turn the link into an arbitrary external redirect. The same Markdown source is part of the normal Blackcap documentation tree and is published through the canonical Microwave Pie documentation site.

Release-note entries are deliberately authored after meaningful product improvement cycles; they are not generated from Git commit messages. Until a version-specific entry is intentionally published, the link opens the release-note structure page rather than inventing historical alpha notes.