Skip to main content
Version: Current

Production School Server Runbook

This is the canonical production procedure for creating and commissioning a Makronexus Education School Server.

Use this page when the goal is to go from approved source code to a working school appliance with a verified release, trusted LAN HTTPS, zero-touch Cloud enrollment, local ERP continuity, and governed Cloud convergence.

One production path

Do not assemble a production School Server by manually chaining npm scripts, Docker commands, source checkouts, development Compose files, frontend-only packs, copied UUIDs, or ad-hoc image tags. The supported release starts with Release-Makronexus-School-Package.cmd in mn-school-be and ends only after the onsite acceptance tests on this page pass.

Field evidence updates this runbook

When a real deployment exposes a mismatch between the release scripts and this page, treat the release implementation as evidence, fix the underlying code/script defect when required, and update this Docusaurus runbook in the same release-engineering change. Do not preserve obsolete field commands for historical convenience.

Production outcome​

A completed deployment has this topology:

When WAN is unavailable, users continue working against the School Server over the LAN if the appliance and its write authority are healthy. When WAN returns, the School Server and Cloud converge under the configured synchronization policy.

End-to-end lifecycle​

Phase 1 — Prepare the release workstation​

Use a controlled Windows release workstation. Keep the backend and frontend repositories as siblings where practical:

C:\Makronexus\
├── mn-school-be\
└── mn-school-fe\

The release workstation requires:

  • Node.js 20 or newer;
  • Git;
  • Docker Desktop with Buildx;
  • Docker running Linux containers;
  • sufficient disk space for production image builds and, for USB releases, the complete air-gap image archive.

Check the workstation before release creation:

node --version
git --version
docker --version
docker buildx version
docker info --format '{{.OSType}}'

The Docker operating-system result must be:

linux

Source-state gate​

Both repositories must be the approved clean source state for a stable release:

cd C:\Makronexus\mn-school-be
git checkout main
git pull
git status

cd C:\Makronexus\mn-school-fe
git checkout main
git pull
git status

For a stable release, both repositories must be on main with no uncommitted changes. Do not bypass the source-cleanliness gate.

Phase 2 — Create the official Makronexus release​

From the backend repository, open:

C:\Makronexus\mn-school-be\tools\

Double-click:

Release-Makronexus-School-Package.cmd

This launcher is the official operator entry point. It delegates to the canonical backend release engine and replaces manual Docker/npm release assembly.

Choose the release type​

The guided builder offers:

[1] Standard connected School Server release
[2] Offline / USB School Server release

Use Standard connected when the School Server will pull the approved digest-pinned Makronexus images from the configured registry.

Use Offline / USB when the field handoff must carry the complete Docker image set. This is the recommended deployment package when registry access at the school cannot be assumed.

Release version​

Use the proposed immutable version format:

YYYY.MM.DD-N

Example:

2026.09.12-2

Do not reuse a completed release version. A release version is an audit identity, not a mutable filename.

Channel​

For a package intended for a real production school, use:

stable

First stable release: signing key​

If the release workstation has no Makronexus release signing key, allow the guided builder to initialize it.

Default local key location:

%USERPROFILE%\.makronexus\release-signing\
├── school-release-private.pem
└── school-release-public.pem

The stable release key is RSA 4096. The private key must remain outside Git, outside the deployment USB, and outside the School Server release artifact.

After initialization:

  1. back up the private key in the approved operations secret-vault/offline custody location;
  2. record the public-key SHA-256 fingerprint in the Makronexus release trust register;
  3. distribute/verify the public key through a channel independent from the deployment USB;
  4. rotate the key under the release-signing policy or immediately after suspected compromise.
Reference public key is not the trust anchor

The finalized release handoff may contain makronexus-school-release-signing-public.pem for convenience. A technician must verify its fingerprint against the independently controlled Makronexus release trust record before trusting it.

Release acceptance​

Only distribute a run that ends with:

RELEASE READY

If the builder ends with:

RELEASE STOPPED

that run is not distributable even if intermediate files exist.

The Release Console finalization step replaces intermediate school-bundle-release-* packaging names with the public Makronexus artifact stem. For an offline/USB stable release, the final handoff 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

Connected mode uses the makronexus-school-server-<releaseVersion>-connected artifact stem and does not require the image tar.

Before copying the release, review RELEASE-REPORT.json and confirm:

  • status is ready;
  • distributable is true;
  • intended release version/channel/mode are correct;
  • source commits/image references are correct;
  • signing identity is correct;
  • artifacts.releaseDirectory, artifacts.archive, artifacts.archiveChecksum and optional image/public-key names describe the files actually present.

RELEASE-REPORT.json is the field filename authority. Do not reconstruct final artifact names from an older runbook.

Phase 3 — Prepare the deployment USB​

Copy the entire releases\<releaseVersion>\ directory to the USB. Do not copy only the .tar.gz file.

For a fully offline clean Windows machine, also place approved prerequisite installers on the USB because Makronexus packages the prerequisite automation but not third-party installer binaries:

USB\
├── <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
└── prerequisites\
    ├── Docker Desktop Installer.exe
    ├── Git-64-bit.exe
    └── wsl.msi

The names above illustrate the current offline convention; use RELEASE-REPORT.json if the report names differ.

If the School Server can use internet temporarily during commissioning, the separate prerequisite installers are optional because the prerequisite bootstrap can use the connected Windows path.

USB custody​

Treat the USB as controlled release media. Do not place the private release-signing key, tenant/school UUIDs, permanent Cloud API keys, HMAC secrets, production database passwords, or copied school data on the generic release USB.

Phase 4 — Prepare the Windows School Server​

The School Server is a dedicated appliance host, not a staff workstation.

Production target:

  • 6+ physical CPU cores;
  • 32 GB RAM;
  • 1 TB-class SSD/NVMe;
  • at least 350 GiB free space;
  • wired Ethernet;
  • AC power, preferably UPS-backed;
  • hardware virtualization enabled;
  • ports 80 and 443 free before first install.

Minimum supported floor is 4 physical cores, 16 GB RAM, 512 GB-class SSD/NVMe and at least 200 GiB free. A host classified REJECTED must not be commissioned.

Copy the handoff locally​

Do not operate the appliance from the USB. Copy the release to local storage, for example:

New-Item -ItemType Directory -Force C:\Makronexus\Incoming
Copy-Item -Recurse E:\<releaseVersion> C:\Makronexus\Incoming\

Replace E: with the actual USB drive letter.

Open PowerShell with Run as administrator:

$R = '<releaseVersion>'
$Root = "C:\Makronexus\Incoming\$R"
Set-Location $Root

If this host already runs a commissioned/enrolled School Server, this is an update, not a clean install. Do not delete C:\ProgramData\Makronexus\SchoolServer, stateful Docker volumes, local trust, or enrollment identity.

Phase 5 — Verify the finalized release before installation or update​

The release archive must be checksum-verified before extraction. Do not hard-code the old intermediate school-bundle-release-$R path.

Use the finalized release report:

$ReportPath = Join-Path $Root 'RELEASE-REPORT.json'

if (-not (Test-Path -LiteralPath $ReportPath -PathType Leaf)) {
    throw 'Missing RELEASE-REPORT.json'
}

if (Test-Path (Join-Path $Root 'DO-NOT-DISTRIBUTE.txt')) {
    throw 'STOP: DO-NOT-DISTRIBUTE.txt exists.'
}

$Report = Get-Content $ReportPath -Raw | ConvertFrom-Json

if ($Report.status -ne 'ready' -or $Report.distributable -ne $true) {
    throw 'STOP: release is not ready/distributable.'
}

$ReleaseDir = Join-Path $Root $Report.artifacts.releaseDirectory
$Archive = Join-Path $Root $Report.artifacts.archive
$ChecksumFile = Join-Path $Root $Report.artifacts.archiveChecksum
$Extractor = Join-Path $ReleaseDir 'scripts\extract-school-bundle-release.ps1'
$OutputDir = Join-Path $Root 'verified'

foreach ($Path in @($ReleaseDir,$Archive,$ChecksumFile,$Extractor)) {
    if (-not (Test-Path -LiteralPath $Path)) {
        throw "Missing finalized release artifact: $Path"
    }
}

powershell.exe `
    -NoProfile `
    -ExecutionPolicy Bypass `
    -File $Extractor `
    -Archive $Archive `
    -ChecksumFile $ChecksumFile `
    -OutputDir $OutputDir

if ($LASTEXITCODE -ne 0) {
    throw "Release verification/extraction failed with exit code $LASTEXITCODE."
}

Expected evidence includes:

Archive checksum verification passed
Extracted release into ...\verified

The extractor script is shipped in the final branded release directory beside the archive. Do not try to execute a script from a directory that exists only inside an archive or from a retired intermediate filename.

Set the verified bundle path from the same report:

$VerifiedRelease = Join-Path $OutputDir $Report.artifacts.releaseDirectory
$Bundle = Join-Path $VerifiedRelease 'school-bundle'
Set-Location $Bundle

Verify the signing trust​

Compare the approved release-signing public-key fingerprint against the independently controlled Makronexus release trust record.

After that independent check, use the report-named public-key reference copy when present:

$PublicKey = Join-Path $Root $Report.artifacts.publicKeyReferenceCopy
Copy-Item $PublicKey "$Bundle\trusted-release-signing-public.pem"

Do not trust a public key solely because it arrived on the same USB as the release.

Phase 6 — Qualify the Windows host​

For a new production commissioning, run the hardware qualification before application installation:

powershell -ExecutionPolicy Bypass -File .\qualify-school-server.ps1

The qualification result must be PASS or an explicitly reviewed WARN.

REJECTED is a hard stop.

Retain:

runtime\server-qualification.json

with the commissioning evidence.

A test host that only passes an explicitly documented testing bypass remains a test host; an update does not convert it into a production-qualified machine.

Phase 7 — Prepare Windows prerequisites​

Connected prerequisite path​

If the clean Windows host can access the internet temporarily:

powershell -ExecutionPolicy Bypass `
  -File .\setup-prerequisites.ps1 `
  -AcceptDockerLicense

This installs/repairs WSL, Virtual Machine Platform, Git for Windows/Git Bash and Docker Desktop, starts Docker, ensures Linux-container mode, and runs the canonical runtime preflight.

If the script reports that Windows must reboot, reboot the machine and rerun the same command. Do not bypass a pending WSL/virtualization reboot.

Fully offline prerequisite path​

If the Windows machine has no internet and is not already prepared:

powershell -ExecutionPolicy Bypass `
  -File .\setup-prerequisites.ps1 `
  -Offline `
  -AcceptDockerLicense `
  -DockerInstallerPath 'E:\prerequisites\Docker Desktop Installer.exe' `
  -GitInstallerPath 'E:\prerequisites\Git-64-bit.exe' `
  -WslMsiPath 'E:\prerequisites\wsl.msi'

After any required reboot, return to the verified bundle and rerun the prerequisite command.

Runtime acceptance​

Run the explicit preflight before installation/update:

powershell -ExecutionPolicy Bypass -File .\preflight-check.ps1

Do not weaken the preflight if Docker resources are insufficient. Production qualification and explicit test-only qualification remain separate policies.

Phase 8 — Configure the School Server environment for a new install​

Existing appliance update

If this School Server is already installed/enrolled, skip new-environment creation. The persistent environment under C:\ProgramData\Makronexus\SchoolServer\.env.school and linked runtime state are authoritative. Do not copy the new release template over them.

For a normal new School Server, create the appliance environment from the shipped template:

Copy-Item .env.school.example .env.school
notepad .env.school

Keep zero-touch identity fields empty​

For a normal new School Server, leave these unset:

# TENANT_ID=
# LOCAL_SCHOOL_ID=
# SITE_ID=

CLOUD_SYNC_REQUIRED=false
CLOUD_BOOTSTRAP_MODE=skip
CLOUD_SYNC_URL=
CLOUD_SYNC_API_KEY=
CLOUD_SYNC_HMAC_SECRET=

The appliance generates its own stable SITE_ID. The one-time Cloud enrollment code establishes tenant/school identity. Permanent machine API/HMAC credentials remain encrypted server-side and never need to be copied to the technician.

Replace every production secret placeholder​

At minimum, set strong values for:

POSTGRES_PASSWORD
MINIO_ROOT_PASSWORD
AWS_SECRET_ACCESS_KEY
JWT_SECRET
DATA_ENCRYPTION_SECRET
NOTIFICATION_CREDENTIAL_SECRET
ARGON2_PEPPER

Use independent secrets. Preserve DATA_ENCRYPTION_SECRET as durable recovery material.

A convenient PowerShell generator for 32 random bytes represented as 64 hexadecimal characters is:

function New-MakronexusSecret {
    $bytes = New-Object byte[] 32
    $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
    $rng.GetBytes($bytes)
    $rng.Dispose()
    return (($bytes | ForEach-Object { $_.ToString('x2') }) -join '')
}

New-MakronexusSecret

Generate separate values for each security secret.

For MinIO, AWS_SECRET_ACCESS_KEY should match the selected MINIO_ROOT_PASSWORD when using the bundle's default MinIO root credentials.

For zero-touch commissioning without a production license already provisioned, the current supported transitional setting is:

LICENSE_ENFORCEMENT_MODE=warn
LICENSE_TOKEN=
LICENSE_PUBLIC_KEY=

Production handover should follow the approved licensing policy.

Do not use demo/seed credentials as a production identity mechanism.

Phase 9 — Offline/USB image verification and import​

Skip this phase for a connected registry release whose images will be pulled from the approved registry.

For an Offline / USB release, return to the release handoff directory and use the image filenames from RELEASE-REPORT.json:

Set-Location $Root

$ImageArchive = Join-Path $Root $Report.artifacts.airgapImageArchive
$ImageChecksum = Join-Path $Root $Report.artifacts.airgapImageChecksum

if (-not (Test-Path -LiteralPath $ImageArchive -PathType Leaf)) {
    throw "Missing offline image archive: $ImageArchive"
}
if (-not (Test-Path -LiteralPath $ImageChecksum -PathType Leaf)) {
    throw "Missing offline image checksum: $ImageChecksum"
}

powershell.exe `
  -NoProfile `
  -ExecutionPolicy Bypass `
  -File $Extractor `
  -Archive $ImageArchive `
  -ChecksumFile $ImageChecksum `
  -VerifyOnly

Expected evidence includes:

Archive checksum verification passed
Verified ...-images.tar without extraction

Load the verified image archive:

docker load -i $ImageArchive

The archive contains the release's Makronexus frontend/backend images and the third-party runtime images referenced by the release manifest.

Phase 10 — Install or update Makronexus Education​

Return to the verified bundle:

Set-Location $Bundle

Existing enrolled appliance — preferred supervised update​

If the host already has a School Server with persistent ProgramData state, existing school volumes, or enrollment.enrolled = true, this is an update.

Do not:

  • delete C:\ProgramData\Makronexus\SchoolServer;
  • delete school-bundle_* stateful Docker volumes;
  • replace the persisted .env.school with the new template;
  • regenerate SITE_ID;
  • generate a new enrollment code merely because the software changed;
  • edit the signed release artifact in place.

For a maintenance-window update with a mandatory pre-update backup/restore proof, use the new verified release's own supervisor:

powershell -ExecutionPolicy Bypass -File .\supervised-update.ps1

For a normal packaged update without the supervisor:

powershell -ExecutionPolicy Bypass -File .\update.ps1

For an offline update, first load the exact report-named image archive as described in Phase 9. The update scripts preserve persistent ProgramData state and enrolled identity and refresh the active release/tasks after health succeeds.

If the appliance was already enrolled but bootstrap failed before any authoritative snapshot was applied, update the software in place, verify enrollment identity is unchanged, then resume bootstrap. Do not repeat enrollment.

See Validation, Updates, and Rollback for update/rollback controls.

New Offline/USB installation​

Use explicit preloaded-image mode:

$env:SKIP_IMAGE_PULL = 'true'
powershell -ExecutionPolicy Bypass -File .\install.ps1
Remove-Item Env:SKIP_IMAGE_PULL -ErrorAction SilentlyContinue

New connected registry installation​

Use the normal install path:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The Windows installer/update must complete the full appliance sequence appropriate to the operation: persistent ProgramData state, hardware/software checks, release/environment verification, LAN identity/time setup, exact image preparation, PostgreSQL/Redis/MinIO continuity, database migrations, backend/workers/frontend/nginx startup, health validation, and autonomous Windows appliance installation/refresh.

A Compose stack that merely starts is not a commissioned School Server.

Durable Windows state​

Commissioned mutable state lives under:

C:\ProgramData\Makronexus\SchoolServer\
├── .env.school
├── active\
├── backups\
└── runtime\

Do not delete this directory as a troubleshooting shortcut. It contains durable appliance configuration, identity, trust material, holds, recovery state, and the active release pointer.

Phase 11 — Prove autonomous appliance operation​

Check appliance status:

powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action Status

Confirm all thirteen scheduled tasks exist:

Get-ScheduledTask -TaskName 'Makronexus-*' |
  Sort-Object TaskName |
  Select-Object TaskName, State

The current production appliance includes runtime/boot recovery, watchdog, power guard, disk guard, nightly backup, certificate/self-resolution maintenance, mDNS LAN discovery, time synchronization, release integrity checking, weekly restore verification, hardware health monitoring, and report-only update discovery.

First backup and restore proof​

For a new production commissioning, create a complete appliance backup:

powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action Backup

Verify recoverability:

powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action VerifyBackup

The supervised updater performs its own pre-update backup and verification. Retain that evidence for an update.

Controlled reboot acceptance​

Restart Windows when the commissioning/update acceptance plan calls for it:

Restart-Computer

After Windows returns, do not manually start Docker Desktop or run Compose recovery commands. The appliance startup/reconciliation tasks must restore the platform automatically.

Then verify from the stable active release path:

cd C:\ProgramData\Makronexus\SchoolServer\active
powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action Status

Automatic recovery after a controlled reboot is a production acceptance gate for a commissioned production host and should be repeated after changes to the Windows control layer.

Phase 12 — Configure and verify school LAN identity and trusted HTTPS​

Give the School Server a stable LAN address through the school's router/DHCP reservation process.

The canonical ERP origin is:

https://school.makronexus.local

On Windows, two local-name mechanisms have different purposes:

  1. Makronexus-Certificate-Maintenance maintains the School Server's own managed loopback hosts mapping for school.makronexus.local / school.makronexus.lan;
  2. Makronexus-mDNS-Responder answers LAN .local queries on the active LAN interface and writes runtime\mdns-responder-status.json.

School-managed DNS/DHCP DNS may also provide the canonical hostname.

Server self-resolution check​

On the School Server:

[System.Net.Dns]::GetHostAddresses('school.makronexus.local')

For server-local requests, the managed hosts mapping normally resolves to 127.0.0.1.

If the server itself cannot resolve the hostname but an HTTPS request succeeds when explicitly pinned to 127.0.0.1, inspect the managed hosts block and Makronexus-Certificate-Maintenance; do not treat that as proof that LAN mDNS is broken.

LAN discovery check​

Inspect:

Get-ScheduledTask -TaskName 'Makronexus-mDNS-Responder'
Get-Content C:\ProgramData\Makronexus\SchoolServer\active\runtime\mdns-responder-status.json -Raw

A recent PASS with the correct active LAN IPv4 provides responder evidence. Confirm actual resolution from a second LAN device as part of acceptance.

Trust the appliance CA on managed clients​

From a second LAN computer, download the School Server local root CA from:

http://<school-server-ip>/makronexus-root-ca.crt

Install it into the managed device's trusted root store according to school/device-management policy.

Then open:

https://school.makronexus.local

There must be no certificate warning. Do not click through TLS warnings; repair name resolution or trust instead.

Phase 13 — Enroll the School Server from Makronexus Cloud only when not already enrolled​

Initial zero-touch enrollment requires WAN access to Makronexus Cloud unless the site is using a separately approved restore/preload workflow.

First inspect local appliance status. If it already reports enrollment.enrolled: true, do not create another enrollment code because of an update or a bootstrap failure. Preserve the existing appliance/site identity and continue to bootstrap/recovery.

For a genuinely new, not-yet-enrolled appliance, in Makronexus Cloud open:

Operations → Offline Sync → School Servers

Select the correct school and create a one-time MNX... enrollment code.

On the trusted school LAN open:

https://school.makronexus.local/appliance-setup

Enter only the one-time enrollment code for the normal flow.

The technician must not type tenant UUID, school UUID, site UUID, permanent API key, or HMAC secret. The server-to-server claim establishes the school scope, preserves the generated stable site identity, and stores long-lived machine credentials encrypted on the School Server.

If enrollment is interrupted before it succeeds, use the governed reissue/resume flow. Do not wipe the database or invent a new SITE_ID.

Phase 14 — Perform or resume the verified initial bootstrap​

After enrollment succeeds, choose Download data in the appliance setup flow.

The initial bootstrap must complete its authoritative reconciliation, snapshot/manifest transfer, file verification, normalized apply, integrity verification, and post-checkpoint delta convergence.

A network interruption or local software defect is a resume/recovery condition, not permission to reset the School Server database.

If bootstrap failed before any snapshot was applied (snapshotId absent/null, cursor/total still zero) and the root cause is fixed in a later signed release, update the enrolled appliance in place and resume bootstrap with the same persisted identity.

Do not commission the appliance until bootstrap shows verified completion.

Phase 15 — Choose Local or Hybrid operation​

The School Server remains the onsite ERP operating node in both Local and Hybrid deployments.

Hybrid production — recommended for normal connected schools​

Choose:

Automatic

Automatic synchronization provides governed periodic Cloud convergence while school users continue to work against the local School Server.

This is the normal Hybrid model:

Staff browsers ⇄ School Server ⇄ Makronexus Cloud

WAN availability changes replication status, not the location where onsite users work.

Manual synchronization​

Choose Manual only where an authorized operator intentionally controls when convergence runs.

Local only​

Choose Local only only when Cloud replication is intentionally disabled by policy. Do not use Local only to hide a connectivity, compatibility, authority, or integrity problem.

A normal fresh zero-touch appliance still requires Cloud for enrollment and initial bootstrap unless an approved restore/preload process is being used.

Phase 16 — Prove local LAN operation​

From a second normal staff computer on the school LAN, open:

https://school.makronexus.local

Use a real authorized school account. Confirm normal authentication, navigation, expected files, and a harmless controlled write in a domain appropriate for commissioning.

The persistent School Server status footer must reflect the real three-plane state:

  1. browser/device → School Server local save;
  2. School Server write authority;
  3. School Server → Cloud synchronization.

A healthy Cloud connection must not hide a write fence. A WAN outage must not be presented as a School Server outage.

Phase 17 — Certify WAN-offline continuity​

This test is mandatory for Local/Hybrid School Server production handover.

Disconnect the site's WAN/internet while leaving the school LAN, router, Ethernet and Wi-Fi operating.

Then verify:

  • https://school.makronexus.local still opens from the second LAN device;
  • the School Server is reachable;
  • write authority is ready;
  • local login/navigation continue;
  • an eligible controlled transaction commits to the School Server database;
  • the footer distinguishes a successful local commit from work waiting for Cloud;
  • no technician switches to Local only merely because WAN is temporarily unavailable.

The expected topology during the outage is:

Staff browsers ⇄ School Server     X     Internet / Cloud

If the browser cannot reach the School Server, that is a local appliance/LAN incident, not normal WAN-offline operation.

Phase 18 — Reconnect and prove hybrid convergence​

Restore WAN connectivity.

For Automatic mode, allow the normal synchronization cycle to run. For Manual, use the authorized synchronization action.

Verify the complete reconnect sequence:

  1. the locally committed outage test change reaches Cloud;
  2. the local pending Cloud queue drains;
  3. no transport retry creates a duplicate mutation;
  4. create or update a different eligible record in Cloud where authority permits it;
  5. verify the School Server pulls/applies that Cloud-side change;
  6. confirm conflicts, if any, are surfaced and governed rather than silently discarded;
  7. confirm final write-authority and synchronization status are healthy.

For a normal Hybrid production school, this bidirectional convergence test is the proof that local continuity and Cloud control are working together.

Phase 19 — Production handover gate​

Do not hand the School Server to the school until all applicable evidence is true:

  • Release was created by Release-Makronexus-School-Package.cmd.
  • Release creation ended with RELEASE READY.
  • RELEASE-REPORT.json says ready / distributable: true and identifies approved source commits, images, release version and signing identity.
  • Field artifact paths came from RELEASE-REPORT.json, not retired intermediate names.
  • Release archive checksum verification passed.
  • Signing key fingerprint was verified against the independent Makronexus trust record.
  • Windows qualification is PASS or reviewed WARN, never REJECTED, for a production-commissioned host.
  • Windows/Docker preflight passed without weakened production gates.
  • Local runtime secrets contain no placeholder values.
  • DATA_ENCRYPTION_SECRET recovery custody is recorded.
  • Offline image archive checksum passed when using USB delivery.
  • Exact offline images were loaded and preloaded-image mode was used intentionally when applicable.
  • Install/update completed the full School Server and autonomous Windows appliance flow.
  • Persistent state exists under C:\ProgramData\Makronexus\SchoolServer.
  • All thirteen Makronexus-* Scheduled Tasks exist.
  • Makronexus-mDNS-Responder is installed and recent discovery evidence is available when exercised.
  • No unexpected appliance hold is active.
  • Initial hardware-health state has no blocking failure.
  • Required backup/restore verification succeeded.
  • Controlled Windows reboot recovered without manual Docker/Compose intervention when required by acceptance.
  • Stable LAN address and school.makronexus.local resolution are configured.
  • Server self-resolution and client LAN resolution have both been checked as separate concerns.
  • A second managed LAN device trusts the appliance CA and sees no HTTPS warning.
  • One-time MNX... enrollment established the correct school identity for a new appliance, or an existing enrolled identity was preserved through update.
  • Permanent Cloud machine credentials remained server-side.
  • Verified initial school-data bootstrap completed.
  • Intended synchronization mode is recorded.
  • Local ERP operation succeeded from another LAN device.
  • WAN-offline local transaction succeeded.
  • Reconnect pushed the local change to Cloud.
  • Cloud → School Server convergence was verified where authority permits it.
  • Final pending/conflict/authority status is understood and acceptable.
  • The server is physically secured, normally on AC/UPS, wired to the LAN, and not used as a staff workstation.
  • Backup/recovery owner and support escalation path are recorded.

Only after this gate passes is the appliance production-ready.

Operational model after handover​

Normal school users use:

https://school.makronexus.local

They do not need Docker, WSL, Git, PostgreSQL, Redis, MinIO, Node.js, or source repositories on their laptops.

The School Server autonomously handles boot recovery, watchdog checks, power/disk protection, backups, certificate/self-resolution maintenance, mDNS LAN discovery, time maintenance, release-integrity checks, restore verification, hardware monitoring, and update discovery according to the appliance policy.

Updates remain governed maintenance operations. Do not automatically activate a newly discovered release merely because a newer version exists.

For deeper operational detail, continue to the reference chapters below.

Reference chapters​