Browse documentation

🧭 Start Here

Blackcap Overview ✨ Blackcap Feature Catalog 🤖 AI Features 🧱 Technology, Administration, and Reliability Installation First Run

📘 User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

🚀 Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

🛠️ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

🍽️ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation 🪄 Adapt Recipe and 🎲 Variations

📅 Plan Meals

Meal Planner

🛒 Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping 🔗 Chrome Extension Shop With

🧺 Manage Kitchen Inventory

🧺 Kitchen Inventory

🖥️ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

🧑‍🍳 Cook with Let’s Cook

🧑‍🍳 Let’s Cook 🧑‍🍳 Let’s Cook Controls and Timers

🤖 Use and Administer AI

🤖 AI in Blackcap 🤖 AI Providers and Connections 🤖 AI Seeds and Usage Support Chat

🔗 Use the Chrome Extension

🔗 Blackcap Chrome Extension 🔗 Chrome Extension Recipe Capture 🔗 Chrome Extension Shop With 🔗 Chrome Extension Release and Privacy

🎮 Play Games

Games and trivia Bramble Harvest — Player Guide Flavor Lab — Player Guide

🔌 Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

⚙️ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform — current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

⚠️ Troubleshoot Blackcap

⚠️ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting 🤖 AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

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.7.1.624-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. With the 0.7.1-alpha base in VERSION, a real commit count is appended as the fourth component before the prerelease label (major.minor.patch.git-count-alpha); older two-component alpha versions retain the legacy display. Without Git/package provenance Blackcap displays v0.7.1-alpha without fabricating a commit count. Git Version remains display/provenance metadata and is never used as a substitute for Git ancestry.

Update policy, automatic checks, and restart updates

Update configuration is available only on package-managed installations at Configuration → Platform → Updates. Source/unmanaged installations do not expose the update configuration page, System update card, or update API surface, and they do not consume update candidates from normal Microwave Pie management-service heartbeats.

The package-scoped policy has two levels:

  • Manual only — Blackcap ignores update candidates carried by normal heartbeats. A System Admin can still choose Check for Updates on the System page for an explicit live check.
  • Automatic check — Blackcap consumes the normalized update decision returned with accepted Microwave Pie management-service heartbeats and also performs one fresh discovery check at each packaged service start. It surfaces Update Available or Downgrade Recommended without downloading anything. Automatic checking does not force the update; only the separately enabled restart auto-apply option authorizes forward activation during that service start.
    • Automatically apply an approved update when Blackcap restarts is an optional dependent setting. On each Blackcap service start, a package pre-start gate performs one immediate fresh Microwave Pie management-service check before Gunicorn begins serving. If the Microwave Pie management service approves a newer forward release, Blackcap prepares and verifies it, hands the normal apply request to the existing independent package updater, and keeps the old release offline. The updater activates and verifies the new release, then starts that new release for normal service.

Automatic restart updates are deliberately forward-only. An approved downgrade is displayed for System Admin review but is never automatically prepared or applied. Failed preparation attempts are also retained in Update History, while failed host activation is retained with the fallback/result details from the independent updater. If a restart-driven target fails host activation, Blackcap remembers that exact failed Release/SHA and does not repeatedly retry it on later service restarts; a System Admin can retry manually, or a newly approved management-service target becomes eligible for the next automatic attempt. If the Microwave Pie management service is unavailable or preparation fails before activation, the restart gate releases the current version to start normally. When an approved forward update is successfully prepared, the current version does not start serving while that update is installed.

While the package pre-start gate is checking or applying a restart-authorized update, Blackcap presents one generic, branded, self-refreshing maintenance page. The public page intentionally does not expose update phase, percentage, target version, package information, database activity, or failure details. A lightweight host-level responder can own Blackcap's normal HTTP port while the application is offline, and GCP Nginx also has a permanent self-contained copy of the same page as an upstream-error fallback. The updater arms a host maintenance marker as soon as it accepts activation, allowing current Nginx configurations to switch to maintenance before Gunicorn is stopped; the permanent fallback also prevents a raw Nginx 404/502 during the handoff. The responder is stopped immediately before the real Blackcap service starts. If no update is available, the maintenance window lasts only for the bounded startup check. If activation fails and rollback is safe, the generic maintenance surface remains available while the updater restores the retained release and then yields the port to that recovered Blackcap service.

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.

The passive status contract exposes the current update policy and 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. For a normal UI-driven operation, when preparation reaches Ready the page changes automatically to Apply Update and Restart Blackcap without a manual refresh. If the package-scoped restart auto-apply setting is enabled, the once-per-service-start pre-start workflow can instead prepare a forward target and immediately hand that verified target to the independent updater before Gunicorn serves requests. During an intentional restart there is therefore no old-release serving window between discovery and activation.

Apply Update

A normal Apply Update action from the System page 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 configured service-start automatic path is the only exception to the interactive confirmation requirement: selecting that platform policy is the administrator's standing authorization to apply an approved forward update during a later Blackcap restart.

The System page header also provides Restart Application for a restart that is not tied to a software release—for example after a System Admin updates Python packages in a mutable source install. The action always requires confirmation and reuses the restart-impact blockers before scheduling the restart. Blackcap discovers the primary systemd unit that owns the current runtime plus active Blackcap companion services for that environment, restarts the companions and primary application together, and then lets the browser reconnect when the application returns. Source Pi/GCP installs use their environment's systemd service permissions; restricted packaged runtimes can fall back to terminating their own same-user service MainPID(s), whose Restart=always units are recreated by systemd.

The restart-impact check also inspects durable AI jobs. Queued work, local post-processing, a checkpointed response, or an OpenAI/Gemini operation with a retrievable provider ID is restart-safe and is shown as advisory information. Durable AI leases carry a service-generation identity for diagnostics, but an unexpired lease remains exclusive even across different service generations. Following a full Blackcap systemd restart, recoverable work held by a previous generation is claimed only after the lease expires (currently up to approximately three minutes, plus the next recovery sweep). Atomic database claiming ensures that only one worker takes the expired lease; it must not preempt a still-running job merely because it belongs to another generation. This prevents scheduled regression workers, old Gunicorn processes, and newly started workers from processing the same AI operation concurrently. A synchronous provider request with no safe retrieval path (notably an in-flight Claude Messages request) blocks a controlled Apply/Restart until that provider window finishes. An unexpected process/VM loss during such a window is recovered as outcome_unknown and is never automatically resubmitted simply because Blackcap restarted. Because no valid response reached Blackcap, the associated AI Seed reservation is automatically returned to the same Organization or Personal account; provider interaction evidence remains available for cost reconciliation.

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 management service also records the Instance's last successful package-managed software update time and origin, distinguishing a Blackcap UI update, a service-start automatic update, and a command-line package update.

The Flask/Gunicorn process does not replace itself. It writes one narrow update request that is consumed by the package-installed systemd updater. The application-side check/download/verification steps are written to the normal inky_admin.service journal, while the privileged activation/restart steps are written by blackcap-update.service; administrators can follow the complete sequence with journalctl -u blackcap.service -u blackcap-maintenance.service -u blackcap-update.service -f. 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. arms the generic host maintenance surface before stopping Blackcap;
  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.

Update history and recent-update notice

Blackcap keeps a bounded package-update history in the protected persistent update-state directory so the record survives immutable release replacement. System → Blackcap Updates → Update History shows the configured number of recent operational entries from that retained history (10 by default, configurable from 1 to the 100-entry host retention ceiling at Configuration → Platform → Updates). Each reconciled Blackcap-managed apply/restore records the source method, start/completion time, from/target/resulting release metadata, duration, package/download provenance when available, terminal phase/message, and whether a failed apply fell back to the existing installation. The detailed privileged updater log remains the troubleshooting source for host-level activation steps; the history is a concise audit rather than a duplicate installer log.

After a successful Service startup automatic update, System Admins see a green Blackcap updated header notice for the configured notification window (24 hours by default, configurable at Configuration → Platform → Updates) only while that service-start update remains the instance's most recent successful version-changing operation. A newer successful Application UI update, command-line update, or restore suppresses the older service-start notice even if the automatic update is still inside the configured notification window. The notice links to the System update card and opens Update History automatically. Ordinary update-available, ready, in-progress, downgrade, and failure states continue to take precedence over that informational success notice.

The main Blackcap service logs the startup check, preparation phases, verification handoff, and terminal reconciliation through its normal service logger. The independent package updater continues to perform privileged activation outside Gunicorn and writes its protected host updater log under /var/lib/blackcap/updates/.

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 the same generic branded maintenance response instead of exposing a raw upstream 404/502. Operational progress remains available only to authenticated Blackcap surfaces and host logs. 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. Published version entries are collapsed by default, with expandable technical or deployment notes; no historical releases are invented from Git commits.

On this page