Skip to main content
Version: Current

Release Artifact Policy

This page defines the release-integrity contract behind the Production School Server Runbook.

A production school is deployed from an artifact created by the official Makronexus School Server release builder in mn-school-be. Source checkouts, development Compose files, frontend-only packs, manually assembled bundles, and ad-hoc Docker tags are not production School Server artifacts.

Official release entry point​

On the controlled Windows release workstation, use:

mn-school-be\tools\Release-Makronexus-School-Package.cmd

The guided launcher delegates to the canonical backend release engine. Operators do not manually chain npm, Docker, manifest, checksum, signing, air-gap, assembly, smoke-test, or archive commands.

A distributable release must end with:

RELEASE READY

A run ending with RELEASE STOPPED is not distributable even if intermediate files exist.

Immutable release identity​

Normal release versions use:

YYYY.MM.DD-N

Example:

2026.08.29-1

Do not reuse a completed release version. The version is an audit identity tying together source commits, image references, signatures, checksums, handoff files, field deployments, backups, incident records, and future updates.

Supported release modes​

Standard connected​

The builder creates/publishes the frontend and backend production images and resolves immutable digest references for the release manifest.

A stable connected release should resolve image references such as:

ghcr.io/<namespace>/mn-school-fe@sha256:...
ghcr.io/<namespace>/mn-school-be@sha256:...

Do not replace these with latest, guessed tags, or locally rebuilt images.

Offline / USB​

The builder creates the same production application images locally and exports the complete release image inventory into the final branded release image archive recorded by RELEASE-REPORT.json.

For release version <releaseVersion>, the current final naming convention is:

makronexus-school-server-<releaseVersion>-offline-images.tar
makronexus-school-server-<releaseVersion>-offline-images.tar.sha256.json

Air-gap image delivery changes image transport only. It does not weaken host qualification, signing, environment validation, appliance automation, zero-touch identity, bootstrap integrity, write authority, or field acceptance.

Canonical handoff shape​

The Release Console finalization step renames intermediate school-bundle-release-* packaging names into the public Makronexus artifact naming scheme. Field operators must use the final names in RELEASE-REPORT.json, not intermediate builder filenames copied from old runbooks.

An Offline / USB stable release is expected to contain a shape like:

releases\<releaseVersion>\
├── makronexus-school-server-<releaseVersion>-offline\
├── makronexus-school-server-<releaseVersion>-offline.tar.gz
├── makronexus-school-server-<releaseVersion>-offline.tar.gz.sha256.json
├── makronexus-school-server-<releaseVersion>-offline-images.tar
├── makronexus-school-server-<releaseVersion>-offline-images.tar.sha256.json
├── makronexus-school-release-signing-public.pem
├── INSTALL-SCHOOL-FROM-USB.cmd
├── RELEASE-REPORT.json
├── RELEASE-REPORT.txt
├── MAKRONEXUS-RELEASE-RECEIPT.txt
└── README-FIRST.txt

A connected release uses the same convention with the -connected artifact stem and does not require the offline image archive. Package-only mode uses the -package artifact stem.

RELEASE-REPORT.json is the filename authority

Do not construct release paths from memory or assume the old school-bundle-release-<version> naming. Read these fields from RELEASE-REPORT.json:

  • artifacts.releaseDirectory
  • artifacts.archive
  • artifacts.archiveChecksum
  • artifacts.airgapImageArchive when present
  • artifacts.airgapImageChecksum when present
  • artifacts.publicKeyReferenceCopy when present

The report describes the final, distributable handoff after Makronexus naming and checksum regeneration.

Release report​

RELEASE-REPORT.json is the machine-readable release evidence. Before field distribution, confirm it identifies the intended:

  • release version and channel;
  • connected/offline mode;
  • frontend source commit;
  • backend source commit;
  • final frontend image reference;
  • final backend image reference;
  • signing key identity/fingerprint when signed;
  • final release directory/archive/checksum names;
  • offline image archive/checksum names when applicable;
  • status: "ready" and distributable: true.

Keep the report with release approval, deployment, support, replacement, and incident records.

Stable signing policy​

Stable production releases are signed by default.

The release private key stays outside Git and outside deployment media. The public key may travel as a reference copy, but trust must come from an independently controlled Makronexus trust record.

The field technician must compare the approved public-key SHA-256 fingerprint with the release trust register before placing the key in the bundle trust location.

Do not treat a public key as trusted merely because it arrived beside the artifact it is supposed to verify.

Trust chain​

The production chain is:

The installer re-verifies signed/checksummed bundle content when the corresponding metadata is present. Never edit checksum/signature material to make modified content pass.

Disposable packaging workspace​

Release construction uses an isolated packaging workspace rather than mutating the checked-in deploy/school-bundle template.

This is important for reproducibility: generating a release must not silently rewrite source-controlled manifest/signature/checksum state in the developer checkout.

Release workstation gate​

A stable source-built release requires clean approved source state. The normal builder refuses stable release creation when frontend/backend repositories are dirty or not on the approved branch.

Do not weaken this gate to package unreviewed source. If emergency release governance requires an exception, document it as an explicit release-policy exception rather than teaching normal operators to bypass the mechanism.

Windows prerequisite media is separate​

The Makronexus School Server release includes Windows prerequisite automation, but it does not redistribute third-party Docker Desktop, Git for Windows, or WSL installer binaries.

For a fully offline clean Windows host, the deployment USB therefore contains two classes of media:

Makronexus release handoff
+
approved Windows prerequisite installers

If internet is available temporarily during commissioning, the connected prerequisite bootstrap can acquire/repair those platform components without separate installer media.

Zero-touch field handoff​

Normal deployment media must not contain or require the technician to type:

TENANT_ID
LOCAL_SCHOOL_ID
SITE_ID
CLOUD_SYNC_API_KEY
CLOUD_SYNC_HMAC_SECRET

The School Server generates stable site identity and discovers the tenant/school scope from the one-time Cloud enrollment code. Permanent machine credentials remain encrypted server-side.

For an already enrolled appliance, a software update preserves the existing persisted identity and machine credentials. A new release version is not a reason to create a new SITE_ID or request a new enrollment code.

USB/media custody​

Never place these on generic release media:

  • release-signing private key;
  • plaintext production database/application secrets prepared for another school;
  • tenant/school/site UUID handoff files for normal zero-touch deployment;
  • permanent appliance API/HMAC credentials;
  • uncontrolled copies of live school data;
  • unapproved installer binaries or altered release files.

Field verification requirements​

Before installation or update:

  1. copy the complete handoff from USB to local School Server storage;
  2. reject any handoff containing DO-NOT-DISTRIBUTE.txt;
  3. require RELEASE-REPORT.json to say status: "ready" and distributable: true;
  4. resolve the release directory/archive/checksum filenames from RELEASE-REPORT.json rather than hard-coding intermediate names;
  5. verify the release .tar.gz with the report-named .sha256.json descriptor before extraction;
  6. independently verify the signing-key fingerprint;
  7. use the trusted public key for bundle signature verification;
  8. when using USB images, verify the report-named offline image archive with its checksum descriptor before docker load;
  9. use SKIP_IMAGE_PULL=true only as the explicit preloaded-image path after the exact manifest images are present locally.

Do not silently fall back from a failed release pull to arbitrary cached images.

Field-proven extraction pattern​

The final handoff contains both the branded release directory and its archive. The extractor script lives in the branded release directory. Therefore the safe Windows flow is:

$Report = Get-Content .\RELEASE-REPORT.json -Raw | ConvertFrom-Json
$ReleaseDir = Join-Path $PWD $Report.artifacts.releaseDirectory
$Archive = Join-Path $PWD $Report.artifacts.archive
$Checksum = Join-Path $PWD $Report.artifacts.archiveChecksum
$Extractor = Join-Path $ReleaseDir 'scripts\extract-school-bundle-release.ps1'

powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File $Extractor `
  -Archive $Archive `
  -ChecksumFile $Checksum `
  -OutputDir (Join-Path $PWD 'verified')

Do not try to invoke an extractor path under an intermediate school-bundle-release-<version> directory that is not present in the finalized handoff.

Never use these as production artifacts​

Do not use source zips/checkouts, developer Docker Compose files, frontend-only support packs, latest tags, manually rebuilt onsite images, mixed files from multiple releases, hand-edited release manifests, copied checksum/signature files from another version, or a partial handoff missing RELEASE-REPORT.json and integrity evidence.

Release acceptance checklist​

  • Official builder was used.
  • Build ended with RELEASE READY.
  • Release version is new and immutable.
  • RELEASE-REPORT.json matches approved source/image intent.
  • RELEASE-REPORT.json says status: "ready" and distributable: true.
  • Final artifact filenames were taken from RELEASE-REPORT.json.
  • Stable signing policy was satisfied.
  • Signing-key fingerprint is recorded in the independent trust register.
  • Release archive and checksum descriptor are present.
  • Offline image archive and checksum descriptor are present when using USB delivery.
  • No release-signing private key is on the handoff media.
  • No permanent appliance Cloud credentials are on normal technician media.
  • No mixed-version files exist.
  • Exact release is retained according to rollback/recovery policy.

Continue with the Production School Server Runbook for the complete deployment sequence or Install the School Bundle for detailed installer behavior.