School Setup

A complete reference for the classroom server — managing the installation, running sessions, connecting to the hub, and keeping the server updated.

System Requirements

Fresh Installation

1. Install Termux from F-Droid

2. Run: pkg install nodejs curl unzip -y

3. Run: curl -fsSL https://ubuntuplay.fly.dev/install.sh | bash

4. Run: ubuntuplay setup and open http://localhost:3000/setup

Android APK Install

For a native Android app experience, download and install the APK directly:

curl -fsSL https://ubuntuplay.fly.dev/install.sh | bash -s -- --apk

Or download the APK manually from the Downloads page and transfer it to your Android device.

The APK is a native app with the classroom server built in — no Termux or terminal needed. Open the app, activate with a license key (or start a Free Trial), and it walks you through the same setup wizard. The app also updates itself: it checks the hub for new releases and offers a one-tap Update Now.

Manual Installation (without installer)

If the installer doesn't work, install manually:

# Install dependencies
pkg install nodejs curl unzip -y

# Download server ZIP directly
curl -fsSL https://ubuntuplay.fly.dev/downloads/uplay-server.zip -o ~/uplay-server.zip
unzip ~/uplay-server.zip -d ~/ubuntuplay/
cd ~/ubuntuplay

# Install Node.js dependencies
npm install

# Start the server
node server.js

Connecting to the Hub

During the setup wizard at http://localhost:3000/setup:

• Hub URL: https://ubuntuplay.fly.dev
• Connection Token: get this from your hub admin or org portal

After connecting, the server receives its license key automatically on the heartbeat sync. Whenever internet is available, the heartbeat runs every few minutes — but connecting once a day is all a school needs.

Running a Session

# Start the server
ubuntuplay start

# Check if running
ubuntuplay status

# Stop the server
ubuntuplay stop

Students connect by:

1. Phone broadcasts a WiFi hotspot — enable in Android Settings → Hotspot

2. Students connect to the hotspot WiFi

3. Open browser → go to the IP shown in Termux (e.g. 192.168.43.1:3000/play)

Teacher Dashboard

Open http://localhost:3000/teacher in a browser on the phone while the server is running.

School leadership (head teacher, deputy, or teachers with granted permissions) can also open the Headmaster LMS at http://localhost:3000/lms — learner enrollment, QR/NFC attendance, student ID cards, announcements, and whole-school reports. See Headmaster LMS →.

HTTPS & Camera Features

The server also listens on HTTPS (port 3443) with an automatic self-signed certificate. Browser features that need a secure context — the LMS camera QR scanner and NFC — work on localhost out of the box; devices connecting over the LAN IP should visit http://<server-ip>:3000/trust once for certificate-trust instructions.

Syncing to Hub

# Manual sync when internet is available
ubuntuplay sync

# Or let it auto-sync (every few minutes whenever the server is online)

Updating

ubuntuplay update

This re-runs the installer, downloads the latest version, and reinstalls dependencies. Your data and settings are preserved.

If you use the Android APK instead, the app checks the hub for new releases on launch and offers a one-tap Update Now that downloads and installs the new APK. Security-critical releases are enforced — the app asks you to update before continuing, but a failed update check (no internet) never blocks an offline classroom.

Troubleshooting

Students can't connect

• Check hotspot is enabled on the phone
• Try the direct IP: http://192.168.43.1:3000/play
• Restart: ubuntuplay stop && ubuntuplay start

npm install fails

The classroom server has no native modules — a plain npm install on Node.js 18+ is all it needs. If it fails, check your internet connection and Node version (node --version), then retry:

npm cache clean --force
npm install

Server won't start — port in use

# Kill any existing node processes
pkill -f "node server.js"
ubuntuplay start