Commercial Blackcap packages can be delivered as customer-specific archives without requiring access to the Blackcap Git repository. A Package selects one reusable Application Release and is associated with one Microwave Pie License / intended Instance relationship. The Package format can be Compiled (the default) or Source / uncompiled. Both formats contain an installer, safe exact-build metadata, and a signed Microwave Pie License Key bootstrap; the payload is either the compiled Blackcap runtime or the captured source release plus its dependency manifest.

Package format and License association

The Package Format is chosen when the Microwave Pie Package is created and remains immutable for that Package. Compiled uses the reusable native Application Release produced by Cloud Build. Source / uncompiled uses the same exact Git commit and release-provenance model but installs a source runtime instead of a Nuitka binary. The destination does not switch between Source and Compiled through the Blackcap update UI: Source stays Source and Compiled stays Compiled.

For standalone compilation, Blackcap explicitly includes the complete third-party package families that contain runtime-selected workers, plugins, generated SDK surfaces, or optional feature modules (gunicorn, mistune, google.genai, openai, anthropic, google_auth_oauthlib, googleapiclient, dropbox, psycopg, and psycopg_pool). An attempted optimization that relied on static-import following did not materially reduce total build duration and produced incomplete standalone runtimes, including missing google.genai._gaos and gunicorn.workers.sync modules. Runtime smoke commands remain in place as defense in depth. Microwave Pie-managed builds emit a diffable compilation report plus a module-family/slow-optimization summary to support further tuning without trading packaging correctness for marginal analysis savings.

A Package is a software-delivery record, not a second license system. The Microwave Pie management service associates the Package with its Microwave Pie License and, after a validated licensed heartbeat, with the installed Instance. The License controls application entitlement, Trial/Perpetual period, scope, binding, revocation, and offline validation. The Package/Download/Release records establish which exact software artifact was delivered. Reusable Application Releases can therefore serve multiple compatible Packages without sharing License credentials between customers.

Package-managed installations also support System → Blackcap Updates. The Microwave Pie management service returns the approved same-platform/same-format target with every accepted instance heartbeat, and Automatic-check installations also perform one fresh discovery request at each packaged service start; a System Admin can force a live check at any time. Discovery remains informational unless the separately configured restart auto-apply policy is enabled, and Manual policy leaves download and activation under explicit System Admin control. When the separate Automatically apply an approved update when Blackcap restarts option is enabled, a package pre-start gate checks before Gunicorn serves, keeps the old release offline when a forward update is available, and lets the independent updater activate/verify the approved package before the new release starts. During that gated restart a lightweight host maintenance responder temporarily serves Blackcap's HTTP port with a self-refreshing update-status page; it is stopped before the real application binds the port. A compatible Previous known-good release is retained locally for rollback. See Application Updates.

Package privacy

Keep the original deployment ZIP private. It contains the signed License Key assigned to that package. Possession of the package is effectively possession of that credential; normal License binding, duplicate-use detection, scope, revocation/replacement, and Trial expiration remain the enforcement controls.

The package does not contain Microwave Pie's private licensing signing key.

Installation

For the initial Linux AMD64/GCP target, the supported package guide assumes a Debian/Ubuntu-style host. Install the bootstrap tools before using the package:

sudo apt-get update
sudo apt-get install -y curl unzip

The Microwave Pie online Installation Guide can generate a fresh package-specific VM/server curl command using the existing Package authorization flow. That command carries a short-lived Package-only credential rather than a Microwave Pie management-service administrative token, downloads the exact package filename used by the extraction step, and fails visibly on HTTP errors. The downloaded archive still remains a credential-bearing private artifact.

Then:

Download or copy the package to the intended Linux host.
Extract the exact ZIP filename shown by the Package Installation Guide into a private working directory.
Run sudo bash install.sh.
The installer verifies the selected release payload SHA-256 and installs a versioned immutable runtime under /opt/blackcap/releases/, while keeping persistent Blackcap state outside that release directory. A Compiled Package installs the prebuilt runtime; a Source Package extracts the tracked source snapshot, creates the release-local Python virtual environment, installs the declared dependencies, and exposes the same packaged runtime dispatcher contract. The package manifest also carries a separate Microwave Pie distribution signature for provenance/audit; MPL1 remains the local licensing trust boundary.
The installer places the License Key bootstrap at a protected 0600 working path and starts the blackcap systemd service.
On startup, Blackcap validates the MPL1 signature and application claim, verifies that the bootstrap package/download metadata matches the installed package metadata, and imports the credential through the normal protected licensing service.
Blackcap reads the persisted license back and removes the protected bootstrap working copy only after successful import.
Blackcap then uses the normal Microwave Pie activation, binding, and instance-reporting workflow. If the Microwave Pie management service is unavailable, existing offline license behavior applies.

The original downloaded ZIP is not modified or deleted by Blackcap. Store or delete it according to your own secure software-delivery policy.

Existing license protection

A package bootstrap never silently replaces a different valid installed License Key. If a valid license is already installed, the package bootstrap remains unused and normal License Details/remediation is required for an intentional replacement.

Reprocessing the same already-imported package is idempotent.

Trial packages

For a packaged Trial, the Microwave Pie management service creates the final signed Trial credential only when the actual package file download starts. Opening the emailed Microwave Pie Package link, viewing the preparation page, or waiting for a reusable release build does not start the Trial. The signed offline fallback therefore starts with package delivery rather than when the administrator originally created the Package record.

Downloading the package again reuses the same signed Trial credential. Reinstalling or re-downloading cannot restart or extend the Trial. The normal online-first-registration versus offline-first fallback-lock rules still apply after installation.

Upgrades and persistence

A package installation separates the versioned runtime from persistent state:

versioned Source or Compiled runtime: /opt/blackcap/releases/<release reference>/;
active runtime link: /opt/blackcap/current;
configuration: /etc/blackcap/;
database, installation identity, License repository, and distribution metadata: /var/lib/blackcap/;
mutable application working state: /var/lib/blackcap/runtime/, including recipe/emoji/noun caches, display previews, AI-generated image candidates, and regression/browser artifacts.

The package-managed release under /opt/blackcap/releases/ is treated as immutable application content in both Source and Compiled modes. Packaged path resolution redirects known generated relative paths to /var/lib/blackcap/runtime/ while leaving bundled code, documentation, migrations, regression fixtures, and Chrome Extension source under the immutable release. Built-in noun/emoji seed assets are copied into the writable runtime only when missing, so upgrades do not overwrite customer-generated cache content. Installing a newer package changes the active runtime link while preserving persistent state. A normal software update does not require a new License Key.

Package metadata includes the authoritative full Git commit SHA. The human Blackcap version is informational.

Package/instance reporting

Blackcap reports only safe distribution metadata through the existing Microwave Pie management-service heartbeat: Package reference, Package Download reference, Release reference, full Git commit, informational version, platform, and manifest digest. The License Key is never included in this metadata.

The Microwave Pie management service uses a validated licensed heartbeat to associate the downloaded package with the actual Blackcap installation and mark it Installed.

Compiled web-server validation

The compiled Linux AMD64 release pins Nuitka to 4.2 so generated C and the persistent compiler cache are reproducible across release builds. The build script also declares BLACKCAP_NATIVE_COMPILE_CACHE_CONTRACT=ccache-content-v1. Microwave Pie uses that explicit contract, together with the pinned Nuitka/Python/GCC identities and the requirements-cloud.txt fingerprint, to decide whether an existing compiler cache is compatible for worker sizing. Packaging-, data-file-, documentation-, certificate-helper-, and smoke-test-only changes must not bump the native compile-cache contract; ccache still validates each object by compiler/content/command before returning a hit. Bump the contract only when native compiler/cache semantics change enough that the existing cache should not be assumed useful.

The compiled Linux AMD64 release explicitly includes the Gunicorn package because Gunicorn resolves some components, including its logger and threaded worker class, from string URIs at runtime. The release build runs the compiled runtime's runtime-check command before publication; if those dynamically selected Gunicorn modules cannot be loaded, the release build fails instead of allowing a package that would only fail after installation.

Initial Linux network setup

The first Linux AMD64 installer binds Gunicorn to 127.0.0.1:8080 and preserves Blackcap's normal external-HTTPS enforcement. For initial setup, use an SSH tunnel or another local-only administrative path rather than opening port 8080 to the internet. Before normal internet-facing operation, place Blackcap behind the supported HTTPS reverse proxy/TLS configuration and restrict host/firewall access as appropriate. See Reverse proxy and TLS.

Troubleshooting

If installation succeeds but the Microwave Pie management service does not show the Package as Installed, verify that:

Blackcap has successfully imported the package License Key;
the License is Active or has otherwise successfully validated online;
instance reporting is enabled and can reach the Microwave Pie management service;
/var/lib/blackcap/blackcap-distribution.json exists and contains the Package/Download/Release metadata installed with the package;
the package was not superseded by a different valid License Key before the heartbeat.

Use Blackcap License Details and its Refresh License Details action to trigger the normal reporting path. Do not paste the full License Key into logs or support diagnostics.

Guided Linux AMD64 installer

Microwave Pie–generated Linux AMD64 Packages now include a guided install.sh and INSTALLATION-GUIDE.md. On Google Compute Engine the installer detects the project ID, VM name, zone, and service account from the metadata server. It asks for the Cloud SQL private/public network choice, Cloud SQL instance name, a single database/user name, and a hidden password. It configures the Cloud SQL Auth Proxy, PostgreSQL environment, Blackcap INI, systemd dependencies, migrations, and application services automatically.

Project-level operations remain deliberate prerequisites rather than permissions the Package grants to itself: enable the Cloud SQL Admin API, grant roles/cloudsql.client to the VM service account, use a Cloud SQL-capable VM OAuth scope, create the Cloud SQL SQL user, and ensure private-IP VPC connectivity when applicable. The installer checks these prerequisites and prints recovery commands without broadening IAM.

Compiled Python migrations

Python migration implementations are compiled under inky_admin.packaged_migrations. The standalone distribution preserves the existing filename-based migration registry with one-line stubs under database/migrations/*.py that import each compiled apply function. This keeps migrations dynamically discoverable without shipping their implementation source.

The PostgreSQL current-schema fast path checks information_schema.tables before touching app_meta, schema_migrations, or other application tables. A completely empty or partially initialized PostgreSQL database therefore returns "not current" without triggering an UndefinedTable error that would poison the transaction when statement savepoints are disabled.

Python dependency contract

requirements.txt is the authoritative superset of Blackcap Python dependencies. requirements-cloud.txt must be an exact package/version subset and excludes only Raspberry Pi hardware packages. tools/verify_python_requirements.py rejects duplicate packages, cloud-only packages, version/extras drift between the files, legacy RPi.GPIO alongside rpi-lgpio, or omission of a feature-level runtime dependency. The verifier also AST-scans Blackcap runtime Python files: a new non-standard-library import must either map to a declared distribution, be Blackcap-owned code, or be an explicitly external hardware driver such as waveshare_epd. This turns future third-party imports into a build/deploy contract instead of another packaging surprise.

The compiled build runs that contract check before installing dependencies, and both source deployment scripts run it before their respective pip install operations. After Nuitka finishes, blackcap-runtime.bin third-party-check imports the feature-level third-party packages that are otherwise easy to miss because they are lazy/optional (Google Drive OAuth, Dropbox, PostgreSQL, GeoIP, OCR/image helpers, Playwright, and the AI SDKs). ai-sdk-check then validates the Gemini, OpenAI, and Anthropic Claude client surfaces separately without making network calls. A base release is not published if either dependency gate fails.

The compiled build also generates an immutable python-dependencies.json manifest from requirements-cloud.txt after the pinned dependencies are installed. The generator verifies every exact direct pin against the build environment, records the requirements-file SHA-256, Python version/implementation, and the resolved transitive runtime dependency graph, then copies that manifest into the standalone release root. The System page exposes this manifest as read-only packaged diagnostics so support can see the exact Python dependency versions embedded in a compiled release. Packaged installations never use the manifest to run pip; changing dependency versions still requires a new Blackcap build/release.

Third-party implementation packages do not have to be proprietary/compiled in principle; they may be carried as normal third-party runtime files when that is the safer or faster packaging choice. The build contract is about availability and functionality in the final runtime, not forcing Blackcap-owned compilation of vendor code.

Compiled runtime validation

Before a compiled base release is published, the build validates the packaged storage contract, builds a fresh SQLite reference schema through the compiled dispatcher, runs an isolated SQLite migration, creates and renders a real editable recipe through the compiled renderer, and then performs a real Gunicorn/Flask HTTP startup smoke test with the compiled binary. The HTTP smoke test requires an HTTP response from a loaded WSGI worker so dynamically imported dependencies omitted by Nuitka cannot pass merely because the Gunicorn master bound the port.

Compiled packages do not assume a sibling application Python interpreter exists. Package-critical helper work is dispatched through the package-installed /usr/local/bin/blackcap-packaged-task wrapper, which loads /etc/blackcap/blackcap.env, sets the package runtime paths, and invokes blackcap-runtime.bin. Managed cron/service work including display refresh, regression scheduling, purge, automatic backup, menu refresh, and the remote Let's Cook watcher uses this shared wrapper rather than invoking loose Python scripts directly. Source/Pi scheduling uses the corresponding tools/run_scheduled_task.py wrapper. Database parity creates its isolated SQLite reference schema through the compiled runtime. The release also includes the Blackcap-Pi-Extension files needed by regression/browser checks and fails the build if required extension assets are absent.

Packaged Flask session secret

Packaged installations must provide a stable INKY_ADMIN_SECRET through the root-managed /etc/blackcap/blackcap.env file. The package installer generates this value automatically and keeps it across normal reinstall/retry flows. The packaged systemd unit enables BLACKCAP_REQUIRE_STABLE_SESSION_SECRET=1, so Blackcap fails closed instead of starting multiple Gunicorn workers with different process-local session keys. The secret value must never be logged or placed in customer-visible package metadata.

Existing database and encryption-key portability

Blackcap database secrets are encrypted with a host-local Fernet key. In the packaged service the default key path is /var/lib/blackcap/.blackcap_pi_secret.key and the companion /var/lib/blackcap/blackcap_license_installation_id because the service HOME is /var/lib/blackcap. The key is deliberately outside PostgreSQL and outside the immutable release tree. Moving an existing PostgreSQL database to a replacement VM therefore also requires moving this key if encrypted credentials are to remain usable.

The packaged runtime exposes database-key-check for the installer. It inspects the existing encrypted license credential and returns a stable status for no encrypted state, missing key, mismatched key, or a valid key. The check does not create a replacement key and does not print secret material. The Microwave Pie–generated installer uses it before service startup to offer three safe paths: import/validate the original key and link the replacement host to the existing database; reset the database public schema and start fresh; or abort to recover the key from the prior VM, persistent disk, or snapshot. Only the original key can preserve access to existing encrypted provider credentials, MFA secrets, license state, and other protected values.

decrypt_secret() likewise never creates a new key while attempting to decrypt existing ciphertext. Key creation remains an encryption/write operation. This keeps a missing migration key distinguishable from a genuinely new Blackcap installation.

Host migration state

An existing Blackcap PostgreSQL database can be moved to another packaged host only when the host-local identity material is moved with it. Preserve /var/lib/blackcap/.blackcap_pi_secret.key and /var/lib/blackcap/blackcap_license_installation_id; also preserve /var/lib/blackcap/blackcap_license_trial_start.json when it exists. The encryption key unlocks encrypted database values, while the license installation identity lets the Microwave Pie management service recognize the replacement VM as the same licensed installation. The Trial first-use file preserves any local offline-fallback lock. These files are intentionally outside the application database and are not embedded in deployment Packages.

If the original encryption key is unavailable, encrypted database values cannot be recovered. The packaged installer can instead reset the Blackcap public schema after an explicit destructive confirmation, or abort so the old host/disk backup can be recovered. A reset is a fresh Blackcap data environment; it is not a way to decrypt or migrate the old data.

Database parity validation in compiled installs

The System-page database parity/schema audit keeps its live-database checks in a compiled install, including migration state, required runtime columns, catalogs, foundation seed data, and licensing integrity. The runtime does not require an inspectable Python source tree to pass that audit. The source-to-temporary-SQLite reference comparison is reported as not applicable for a compiled runtime because the immutable release build already exercises the bundled SQLite reference/schema path before publication. Source and Raspberry Pi installations continue to run the full source-and-database parity comparison.

Compiled AI provider SDK validation

Compiled releases explicitly include the supported AI provider SDK packages: google.genai (google-genai), openai, and anthropic. Cloud Build runs a network-free ai-sdk-check against the final blackcap-runtime.bin; it imports all three SDKs, constructs clients, and verifies the Gemini/OpenAI/Anthropic model and request surfaces Blackcap uses before a base release can be published. This prevents lazy provider imports from being omitted by Nuitka while keeping source installations on the same pinned requirements-cloud.txt dependencies. Anthropic is pinned at anthropic==1.3.0 in source and cloud requirements.

Compiled database parity regression behavior

The System database parity audit remains available in compiled installations and continues to expose any live-database findings for administrator review. Because source-to-SQLite code parity is a build-time concern for an immutable compiled release, a completed compiled-runtime parity audit is advisory rather than a regression gate. A failed/timed-out audit job still fails regression; source installations remain strict and require a clean parity result.

Package provenance and local rollback

Manifest schema 2 records both the exact full Git SHA and the numeric Git Version used to build the package, plus deployment mode, target platform, Release reference, and packaged migration boundary. The full SHA remains authoritative internally; Git Version is the normal human-facing build number.

After a successful package-managed UI update, Blackcap retains the prior healthy immutable release locally as /opt/blackcap/previous. This rollback slot is independent of the Microwave Pie management service's short-lived generated ZIP retention and is not rotated until the replacement release has passed exact post-restart provenance checks. See Application Updates.

The package installer is the root authority for UI-updater readiness: it installs the updater executable and systemd units, enables and starts blackcap-update.path, and refuses to complete the service-enablement stage unless the path unit is enabled and active. The running Blackcap process is intentionally unprivileged. It uses live systemd status when queryable and otherwise falls back to the root-installed unit/enablement structure rather than misreporting an inaccessible systemd query as an inactive updater.

Chromium itself is not downloaded during native compilation. The compiled package retains the Playwright Python runtime/data contract, while the package installer invokes blackcap-runtime install-browser on the target host when the optional browser regression runtime is prepared. This avoids paying the browser-download cost on every warm compile.

On this page