Skip to main content
Version: Current

Prerequisites and Deployment Handoff

Use this page as the go/no-go gate before travelling onsite. The normal field flow is zero touch for school identity: do not pre-copy tenant, school or site UUIDs into a fresh appliance.

1. Cloud-side readiness​

An authorized Cloud operator must confirm:

  • Makronexus Cloud is reachable over HTTPS;
  • the tenant and target school already exist;
  • the operator can access Operations → Offline Sync → School Servers;
  • the operator has the required School Server permissions for the intended work;
  • the approved release is known;
  • Cloud can issue one-time provisioning/replacement codes;
  • any required licensing/release policy is available.

For a normal new appliance, the field technician needs the school selection made by the Cloud operator, not its UUIDs.

2. Identity: generated and discovered​

The normal initial state is:

# 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=

During enrollment:

  • the School Server generates and durably preserves its stable SITE_ID;
  • the one-time Cloud code establishes tenant/school scope;
  • non-secret identity is persisted under runtime/.env.local;
  • permanent machine credentials are encrypted server-side.

Advanced pre-provisioning may set all identity and machine-credential fields as a governed automation path, but never mix a partially pre-provisioned identity with zero-touch setup.

3. Host readiness​

The host must reliably run Docker Compose services for PostgreSQL, Redis, MinIO, backend, frontend, nginx, workers, migrations and initialization jobs.

For a Windows laptop or PC, complete Windows School Server Qualification before application installation. The enforced production floor is 4 physical cores, 16 GB RAM, 512 GB-class SSD/NVMe storage, 200 GiB free space, 64-bit Windows, enabled hardware virtualization, and free ports 80/443. The normal production target is 6+ physical cores, 32 GB RAM, a 1 TB-class SSD/NVMe drive, and at least 350 GiB free.

A Windows School Server must be a dedicated appliance host. Do not use the same laptop as a normal staff workstation.

Confirm:

  • Windows qualification completed without REJECTED when applicable;
  • the qualification report runtime\server-qualification.json is retained with the commissioning record;
  • durable local SSD/NVMe storage with growth headroom;
  • host does not sleep/hibernate during school operation;
  • a stable LAN address/DHCP reservation;
  • client-to-server LAN connectivity on ports 80 and 443;
  • system time synchronization is available;
  • school.makronexus.local can resolve by mDNS/Avahi or managed DHCP/DNS; if not, infrastructure has an explicit DNS plan;
  • backup/recovery ownership is assigned before production data is created.

Docker Desktop, Git Bash and WSL do not have to be installed manually before arriving onsite when the approved Windows bundle contains setup-prerequisites.ps1. The release bootstrap can install or repair them on the dedicated School Server host.

4. Windows prerequisite bootstrap and runtime preflight​

The Windows bundle now separates software preparation from runtime acceptance:

  • setup-prerequisites.ps1 installs or repairs WSL, Virtual Machine Platform, Git for Windows/Git Bash and Docker Desktop;
  • preflight-check.ps1 remains the fail-closed runtime gate for Docker Engine, Linux containers, Compose v2, CLI tooling, CPU and RAM;
  • install.ps1 -BootstrapPrerequisites can invoke prerequisite setup before deploying the ERP stack.

Do not weaken or bypass the preflight just because the bootstrap installed successfully.

Connected Windows host​

Open PowerShell as Administrator in the extracted school-bundle directory.

To prepare the host first:

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

Or use the integrated first-install flow:

powershell -ExecutionPolicy Bypass -File .\install.ps1 `
  -BootstrapPrerequisites `
  -AcceptDockerLicense

-AcceptDockerLicense is deliberately explicit and is only needed when Docker Desktop must be installed. It records the operator's decision to accept Docker's applicable license terms rather than silently accepting third-party terms inside the Makronexus bundle.

The connected bootstrap uses WinGet when Git or Docker is missing and updates WSL from Microsoft when possible.

Reboot-required state​

Enabling WSL or Virtual Machine Platform can require a restart. If the bootstrap reports a reboot requirement:

  1. restart Windows;
  2. open an elevated PowerShell session again;
  3. rerun the same bootstrap or install.ps1 -BootstrapPrerequisites command.

The prerequisite flow is idempotent. Completed steps are detected and skipped. Do not attempt to force the application install through a pending WSL/virtualization reboot.

Fully offline / USB host​

The Makronexus release contains the prerequisite automation, not third-party Docker/Git/WSL installer binaries. For a fully offline Windows installation, support must place approved installers on the USB handoff and pass them explicitly:

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'

The same paths can be passed through install.ps1 with -BootstrapPrerequisites -OfflinePrerequisites.

This prerequisite step is separate from the air-gap Docker image archive. A USB deployment therefore needs both the approved Windows prerequisite installers when the host is not pre-provisioned and the Makronexus image archive required by the release.

Check-only mode​

For a host that should already be prepared:

powershell -ExecutionPolicy Bypass -File .\setup-prerequisites.ps1 -CheckOnly

Check-only mode makes no prerequisite changes and finishes by running the canonical preflight.

Canonical Windows acceptance gate​

The Windows software preflight verifies Docker Engine, Linux containers, Docker Desktop CLI, Compose v2, at least 4 Docker CPUs and at least 8 GiB Docker RAM; 12 GiB or more Docker RAM is recommended. It also verifies that Git Bash can see the bundle-required docker, curl, sha256sum, tar, and openssl commands.

A machine can pass physical qualification and still be badly constrained inside Docker, so keep hardware qualification and software/runtime preflight separate.

On Linux, run the packaged preflight-check.sh; the Windows bootstrap is not used.

5. Network and trust plan​

LAN​

The canonical ERP URL is:

https://school.makronexus.local

The appliance creates its own local CA and TLS certificate. The installer prints the bootstrap location for the CA:

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

Managed client devices must trust that CA before normal ERP use. Do not train staff to bypass browser certificate warnings.

The legacy alias school.makronexus.lan may exist as a certificate/DNS alias, but the documented canonical name is .local.

WAN​

A connected first enrollment/bootstrap needs outbound HTTPS to Makronexus Cloud. Registry access is also needed unless the exact images are preloaded through the approved air-gap process. Day-to-day WAN can fail without stopping LAN ERP operation.

Time​

The bundle configures/inspects the host time-sync facility and the runtime measures clock posture against APPLIANCE_NTP_SERVER (default time.cloudflare.com). Clock drift matters because signed machine requests have a replay window.

6. Local secrets​

Prepare unique strong values for the local runtime, including PostgreSQL/MinIO credentials and application security keys such as:

JWT_SECRET
DATA_ENCRYPTION_SECRET
NOTIFICATION_CREDENTIAL_SECRET
ARGON2_PEPPER

DATA_ENCRYPTION_SECRET is durable recovery material. It protects enrolled machine credentials and setup capabilities. Preserve it securely across update and restore; do not casually rotate it.

Normal field technicians do not need plaintext long-lived Cloud API/HMAC credentials.

7. Managed LAN identity defaults​

The current bundle template includes:

APPLIANCE_LAN_HOSTNAME=school.makronexus.local
APPLIANCE_LAN_ALIAS=school.makronexus.lan
APPLIANCE_CERT_VALID_DAYS=90
APPLIANCE_CERT_RENEW_BEFORE_DAYS=30
APPLIANCE_NTP_SERVER=time.cloudflare.com
APPLIANCE_BACKUP_MAX_AGE_MINUTES=1560

Change these only as part of an approved infrastructure profile. Certificate trust, DNS and allowed origins must remain coherent with the URL used by staff.

8. Cloud operator permissions​

The fleet operator needs the dedicated School Server permissions appropriate to the action. Typical lifecycle permissions cover reading fleet posture, enrolling and managing/revoking/replacing servers. Keep these rights narrower than normal school administration.

School administrators separately need the synchronization permissions required to view status, configure permitted sync modes, trigger synchronization and resolve conflicts.

9. Release handoff​

The field team should receive:

  • exact approved release version;
  • verified school bundle/archive;
  • checksum/signing trust material shipped for that release;
  • registry access instructions or exact air-gap image set;
  • local secret custody procedure;
  • approved Cloud origin (the UI has the official origin by default; custom/self-hosted is an advanced override);
  • name/contact of the Cloud operator who will create the MNX... code;
  • client CA-distribution plan;
  • stable LAN/DNS plan;
  • recovery/backup owner;
  • rollback/known-good release reference;
  • escalation route.

For Windows schools, confirm the shipped bundle includes qualify-school-server.ps1, setup-prerequisites.ps1, preflight-check.ps1, WINDOWS-PREREQUISITES.md, and install.ps1 from the same verified release.

For connected Windows hosts, no separate Docker/Git installer files are required if WinGet and internet access are available. For fully offline hosts that are not already prepared, the USB handoff must additionally contain approved Docker Desktop, Git for Windows, and WSL installers matching support policy.

Do not put tenant UUID, school UUID, site UUID, API key or HMAC secret into a normal technician handoff simply because older documentation required them.

10. Recovery prerequisites​

Before handover, decide where durable recovery material is held. At minimum protect:

  • PostgreSQL data/recovery points;
  • file/object data according to the DR policy;
  • the durable appliance encryption secret;
  • release/version records and known-good artifact;
  • appliance/local-CA continuity where your restore model requires it.

A same-machine copy is not a substitute for recovery from total appliance/disk loss.

11. Go/no-go checklist​

  • Tenant and school exist in Cloud.
  • Authorized Cloud operator can manage School Servers.
  • Approved release artifact and trust material are present.
  • Windows host passes qualify-school-server.ps1 without REJECTED when applicable.
  • Windows qualification report is retained and warnings are resolved or explicitly accepted.
  • Windows prerequisite bootstrap completed successfully, or -CheckOnly confirms the host is already prepared.
  • Any bootstrap-requested Windows reboot was completed and the bootstrap rerun.
  • Host passes release software preflight.
  • Local secrets contain no placeholders.
  • DATA_ENCRYPTION_SECRET custody is defined.
  • Fresh zero-touch install leaves tenant/school/site identity unset.
  • Ports 80/443 are reachable on the school LAN.
  • school.makronexus.local resolution plan is known.
  • CA trust distribution to managed clients is possible.
  • Host NTP/time-sync facility is available.
  • Cloud HTTPS is reachable for commissioning.
  • Registry or air-gap image path is ready.
  • Offline Windows handoff includes prerequisite installers when the host is not pre-provisioned.
  • Recovery/backup owner is assigned.
  • A second LAN device is available for acceptance testing.
  • The team can safely disconnect/reconnect WAN for certification.

Continue with Release Artifact Policy, then Install the School Bundle.