Skip to main content
Version: Current

Browser Enrollment and Initial Bootstrap

The normal field setup is deliberately simple: the technician enters a one-time MNX... code. The School Server generates its own stable site identity and discovers tenant/school identity from Cloud.

Before you begin​

Confirm:

  • the bundle passed trusted HTTPS readiness;
  • the client trusts the appliance CA;
  • https://school.makronexus.local/appliance-setup opens;
  • Cloud has the correct school record;
  • the Cloud operator has School Server lifecycle permissions;
  • WAN access to the approved Cloud HTTPS origin is available.

1. Create the one-time code in Cloud​

In Makronexus Cloud open:

Operations → Offline Sync → School Servers

For a new school with no active primary School Server, create the provisioning code for the correct school. The Cloud operator selects the school; the technician does not copy its UUID.

For a replacement, use the governed Replace server flow instead of creating an unrelated new primary. See Backup, Restore, and Server Replacement.

2. Local setup input​

The setup page uses the official Cloud origin by default. A different Cloud address is an advanced override for approved staging/self-hosted deployments and must use HTTPS in production.

Normal input:

One-time enrollment code: MNX....

There is no normal tenant ID, school ID, or site ID field.

3. Zero-touch claim​

Behind the setup page:

  1. the appliance creates/persists its stable site identity before exchanging credentials;
  2. the local backend sends the one-time code and site identity to Cloud;
  3. Cloud verifies code expiry/scope and the intended new/replacement appliance record;
  4. Cloud issues machine credentials into a recoverable exchange;
  5. the local backend durably encrypts and stores those credentials;
  6. the appliance confirms the exchange using its new signed machine identity;
  7. Cloud finalizes the enrollment;
  8. non-secret tenant/school/site identity is persisted under runtime/.env.local;
  9. the browser receives only a short-lived setup session.

Browser JavaScript must never receive the permanent API key or HMAC secret.

4. Interrupted enrollment recovery​

Provisioning is designed for power loss/browser loss around credential exchange.

If setup is interrupted:

  • do not delete the appliance database;
  • do not invent another site ID;
  • generate/reissue a fresh one-time code through the existing unconfirmed appliance/replacement record;
  • the control plane revokes abandoned temporary credential/exchange state rather than creating uncontrolled duplicate server identities.

Authenticated confirmation is separate from the short-lived human code, so a server that durably stored credentials can safely finish confirmation after an interruption.

5. Verified initial bootstrap​

After identity is established, run Download data from the setup workflow.

The bootstrap is not an unbounded blind history replay. The intended integrity model is:

The process fails closed when integrity cannot be established. File bytes are verified before dependent metadata is treated as usable.

Bootstrap progress is durable. A network interruption is a resume event, not a database-wipe event.

6. Choose synchronization mode​

After bootstrap is complete:

Automatic​

Recommended when periodic Cloud convergence is desired. The local School Server remains the onsite operating node; Cloud replication runs when connectivity permits.

Manual​

An authorized operator explicitly starts replication.

Local only​

Cloud replication is intentionally disabled. Do not use Local only as a way to hide a broken connection or compatibility problem.

7. Runtime activation​

Finishing setup activates the School Server runtime in the current process; zero-touch commissioning does not require a manual backend restart merely to acquire school scope or start replication.

The dynamic school scope and enrolled identity are also persisted so the next restart comes back with the same identity.

8. Replacement candidate behavior​

A replacement candidate can enroll and bootstrap without becoming authoritative. During commissioning it remains write-fenced. This is intentional: the old primary continues owning school writes until the guarded cutover.

The local footer should make that state explicit rather than displaying a reassuring local-write status.

9. Setup-session expiry​

The browser setup capability is short lived. If it expires, use the governed re-authorization/reissue path. Do not create a permanent browser setup credential and do not reset completed bootstrap work simply to get a new session.

10. Cloud fleet verification​

After setup, confirm the School Servers workspace shows the expected appliance/candidate and live posture, including applicable identity, version/protocol/schema/build telemetry, last heartbeat, bootstrap/setup readiness and health information.

For a normal new server, it should be the active primary after commissioning. For a replacement candidate, it stays non-primary until explicit cutover.

11. Acceptance checklist​

  • Setup opens over trusted HTTPS.
  • Technician was not asked for tenant/school/site UUIDs.
  • Only the one-time code was transferred for normal enrollment.
  • Long-lived machine credentials stayed server-side.
  • Stable site identity persisted under runtime state.
  • Interrupted exchange can be safely retried/reissued without creating duplicate primary identity.
  • Bootstrap reaches verified completion.
  • Required file objects pass transfer integrity checks.
  • Post-checkpoint deltas converge.
  • Sync mode is intentional.
  • Cloud fleet shows the expected primary/candidate role.
  • Replacement candidate, if applicable, remains write-fenced before cutover.

Continue with Authority and Offline Semantics.