Skip to main content
Version: Current

Install the School Bundle

The canonical production artifact is the backend-owned school-bundle. Do not install production schools from source checkouts or development Compose files.

1. Prepare the release directory​

Work from the exact verified release bundle. Keep release-manifest.json, checksum/signature material, scripts, Compose file and environment template from the same release.

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

For a normal zero-touch install, leave school identity and permanent Cloud machine credentials 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=

Fill the local database/object-storage/application secrets and approved license settings. Never leave CHANGE_ME... placeholders.

For an existing enrolled appliance update, do not create a new .env.school from the template and do not re-enroll. Use the persistent ProgramData environment and the packaged update flow described in Validation, Updates, and Rollback.

2. Qualify a Windows School Server before installation​

Run both Windows gates explicitly before the field window:

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

The supported hardware floor remains 4 physical cores, 16 GB RAM, 512 GB-class SSD/NVMe, 200 GiB free, 64-bit Windows, enabled firmware virtualization and free 80/443 ports. Production target is 6+ cores, 32 GB RAM, 1 TB-class SSD/NVMe and 350+ GiB free.

The qualification report is written to:

runtime\server-qualification.json

The Windows preflight separately verifies Docker Engine, Linux containers, Compose v2, supported Windows Scheduled Task/network/firewall primitives, at least 4 Docker CPUs and at least 8 GiB Docker RAM. A rejected host cannot continue through the normal installer.

See Windows School Server Qualification.

3. Persistent Windows appliance state​

On Windows, mutable commissioned state is moved out of the extracted release directory before Compose installation.

Canonical location:

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

prepare-windows-appliance-state.ps1 preserves the supplied .env.school as the canonical ProgramData environment, links the release-local .env.school back to it, migrates/preserves runtime state, and links the release-local runtime directory to the persistent runtime.

This matters because docker-compose.yml uses service-level env_file: ./.env.school. Passing --env-file to Compose alone does not change that relative service env_file; the release-local link prevents stale configuration.

Persistent ProgramData state must survive updates and release-folder replacement. Do not delete it to “reset” an appliance.

Important persistent runtime material includes:

runtime\
  .env.local
  server-qualification.json
  windows-state.json
  active-release.json
  lan-identity.json
  hold-*.json
  tls\

The stable active junction is switched to the healthy release after autonomous task registration, so Scheduled Tasks are not pinned to an obsolete extraction folder.

4. Run install as Administrator​

Open Windows PowerShell with Run as administrator:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The Windows production sequence is:

Installation is not considered complete if persistent-state preparation or the autonomous task layer fails.

5. Autonomous Windows task installation​

install-windows-appliance.ps1 registers thirteen Makronexus-* Scheduled Tasks for:

  • Docker Desktop/container runtime startup recovery;
  • boot Compose reconciliation;
  • two-minute watchdog/self-heal;
  • power guard and graceful critical-battery shutdown;
  • disk-pressure protection;
  • nightly complete backup;
  • LAN certificate maintenance and server self-resolution;
  • LAN mDNS advertisement/response for school.makronexus.local;
  • Windows time synchronization;
  • installed-release integrity checking;
  • weekly restore verification;
  • hardware degradation monitoring;
  • report-only update availability checking.

It also configures AC sleep/hibernate/lid policy, LocalSubnet-only HTTP/HTTPS firewall access, and the stable ProgramData active release path.

See Windows Autonomous Appliance.

6. Confirm the task set​

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

All thirteen tasks must exist before handover. Do not commission a server where install.ps1 succeeded at Compose startup but autonomous task installation failed.

7. Air-gap image delivery​

Air-gap image delivery removes the registry dependency; it does not remove hardware/software qualification or Windows appliance automation.

Import the exact release image archive with the packaged helper, then run the release's preloaded-image path. Example:

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

A new zero-touch school still needs Cloud connectivity long enough for enrollment and initial bootstrap unless a separately approved restore/preload procedure is used.

8. Managed LAN TLS and local name resolution​

The canonical local endpoint remains:

https://school.makronexus.local

HTTP port 80 is the bootstrap/redirect surface, including the appliance root CA. HTTPS 443 is the normal application path.

On Windows, ongoing certificate maintenance uses native NIC/IP discovery plus OpenSSL. The server certificate is renewed when missing/invalid, near expiry, or when hostname/alias/active IPv4 addresses change. The local CA remains stable so client trust survives routine server-certificate renewal.

The same maintenance path keeps the School Server's own managed Windows hosts block mapped to 127.0.0.1, while Makronexus-mDNS-Responder answers LAN .local discovery on the active LAN interface. School-managed DNS/DHCP DNS may also provide the canonical name.

If the server itself cannot resolve school.makronexus.local, inspect the managed hosts block and Makronexus-Certificate-Maintenance. If other LAN devices cannot resolve it, inspect Makronexus-mDNS-Responder, runtime\mdns-responder-status.json, and the LAN/DNS path.

9. Trust the appliance CA​

From a managed LAN client open:

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

Trust the CA according to device-management policy, then open:

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

Do not proceed through a browser certificate warning. Fix DNS/trust instead.

10. Initial appliance acceptance before enrollment​

On Windows, before opening the browser setup flow:

powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action Status
powershell -ExecutionPolicy Bypass -File .\hardware-health.ps1
powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action Backup
powershell -ExecutionPolicy Bypass -File .\windows-appliance.ps1 -Action VerifyBackup

Then perform one controlled Windows reboot and verify the server returns healthy without manually opening Docker Desktop or issuing Compose recovery commands.

11. What the normal installer does not ask for​

The normal zero-touch field process does not require the technician to type:

TENANT_ID
LOCAL_SCHOOL_ID
SITE_ID
CLOUD_SYNC_API_KEY
CLOUD_SYNC_HMAC_SECRET

Those identities are generated/discovered during browser enrollment; permanent machine secrets remain server-side.

An update to an already enrolled appliance preserves those identities and credentials. A release update is not an enrollment event.

12. Advanced pre-provisioned mode​

Controlled automation may configure all identity values plus complete HTTPS Cloud machine credentials and choose CLOUD_BOOTSTRAP_MODE=required or optional.

Use this only as an explicitly governed automation profile. Never set partial tenant/school/site identity, and never mix half-configured machine credentials with zero-touch enrollment.

Install success criteria​

Before browser enrollment:

  • Windows qualification is not REJECTED.
  • software/Docker preflight passed.
  • ProgramData persistent environment/runtime exist.
  • release-local .env.school and runtime resolve to persistent state.
  • release integrity/environment checks passed.
  • PostgreSQL, Redis and MinIO are healthy.
  • migrations and application startup completed.
  • managed CA/server certificate exist and trusted HTTPS readiness passes.
  • all thirteen Makronexus-* tasks exist.
  • active-release.json identifies the intended active release.
  • no unexpected appliance hold exists.
  • initial hardware health has no FAIL.
  • first complete backup and restore proof succeeded.
  • controlled reboot recovered automatically.
  • another LAN device can resolve/reach the appliance and trust the CA.

Next: Windows Autonomous Appliance, then Browser Enrollment and Initial Bootstrap.