Guides

Start Here

Set Up Your Classroom from Scratch

This guide takes a classroom from a pile of computers to a working TechLit lab: network, first computer, updates, curriculum, and languages. It is written for teachers. Each setup step has a Step by Step tab; where there are extra commands or configuration, open the More Detail tab beside it — use whichever you need.

A TechLit classroom runs on its own local network (LAN). Setting up the network never needs internet. A few later steps do use it — installing languages, updating from Bastion — and those guides say so.

Only here for one task? Jump straight to it:

Update working computers: Updates
Fix Wi-Fi or cables: Network troubleshooting
Set up languages for the code curriculum: Setting Up Programming Languages
Add games: Installing Games

What you’ll need

One computer to act as the server — the fastest one that has an Ethernet port
The remaining computers (clients)
One or two routers, plus Ethernet Cable s (the grey or white cables)
A TechLit installer USB. If you don’t have one, follow Create an Installer USB first.

Note

server and client are network roles, not user roles. Students use every computer in the classroom, including the server.

[!WARNING] Two rules that break a classroom if ignored

Only one computer may have the Role server.
The server must be connected by cable — never over Wi-Fi.

Connect the hardware

1. Choose and connect the server

Pick the fastest computer with an Ethernet port. Connect it directly to the main router with an Ethernet cable.

2. Place and connect the routers

One router: place it in the middle of the room for best signal.
Two routers: connect the second one to the first with a cable, and keep them as far apart as possible.

3. Connect the other computers

Whenever possible, connect the remaining computers to a router with cables instead of Wi-Fi — it is much faster and more reliable.

Set the network roles

Every computer gets a Role — server or client — set with the tl-sys-configure tool (logged in as admin).

1. Set up the server

On the server, run tl-sys-configure and set the Role to server.

2. Set up the clients

On each computer configured as a client, run tl-sys-configure and:

Set the Role to client.
Set the Wi-Fi Name ( SSID ) to match the network.

3. Turn off Wi-Fi on wired machines

On the server and any computer with a cable, switch Wi-Fi off using the network icon in the corner of the screen.

tl-sys-configure writes role, hostname, wifi_name, and wifi_password to /srv/secure/config.json. Re-run it any time to change those values.
Confirm the address server (DHCP) is running:
```
rsv status dhcpd4
```
It should show run. If it shows down, restart it with sudo rsv restart dhcpd4.
Two routers? Split the load: give half the clients one SSID and half the other.
Re-check that no other computer is set to server — two servers break the whole network.

For cable diagrams and the full setup, see the Network & Wi-Fi guide.

Prepare the installer USB

The installer USB boots a computer into the recovery environment used in the next step. Create one with the Create an Installer USB guide — it erases the USB drive completely. Skip this step if you already have a working installer.

Provision the first computer

Caution

tl-hw-prepare erases everything on the internal drive. Double check the drive name before pressing Enter.

1. Boot from the USB

Restart the computer and boot from the TechLit USB drive.

2. Identify the internal drive

lsblk

Look for the drive that is much larger than your USB — common names are /dev/sda, /dev/nvme0n1, or /dev/mmcblk0. This is your

Target Drive .

3. Install the system

Replace /dev/sdX with your drive and tl-xxxx with the computer’s tag:

tl-hw-prepare /dev/sdX tl-xxxx

4. Finish and reboot

When you see the success message, type reboot and pull the USB out as the computer restarts.

Two commands exist — choose by situation:

New or wiped computer: tl-hw-prepare /dev/sdX tl-xxxx creates the partitions and installs everything.
Existing computer, keep the data: tl-hw-update-desktop /dev/sdX unpacks a desktop image over the current system. Pin a version by adding it: tl-hw-update-desktop /dev/sda 23.1.1.

You can set the Wi-Fi name during the install:

WIFI_NAME="TechLit Emacs" tl-hw-prepare /dev/nvme0n1 tl-0606

Typed the wrong tag or Wi-Fi name? Let the install finish, then fix it with tl-sys-configure — see Troubleshooting Provisioning.

Small devices (32GB or less)

Chromebooks and Mini Computers must not use this method. Follow Small Storage Devices instead.

Update the classroom

Once one computer has the update files, spread them through the room.

For standard desktop computers, update from a prepared USB drive — see Standard Desktop Computers:

Plug the USB in and open “Update Components” (or run tl-comp-update).
Choose Update → Update Desktop (Using USB).
Pick your USB drive and wait for it to finish, then unplug the USB.
Reboot when prompted.

To patch computers over the LAN, without a USB stick:

Get the update files onto one machine — bring them in on a USB drive or use a computer that already has them (Get Update Files).

Copy them to the computer that needs them:

# Run on the computer that needs the update
tl-comp-pull desktop tl-1234.local

Apply them with Installing Local Patches — tl-archive-install admin for components, tl-img-unpack plus tl-img-restore for desktop patches.

Major version jumps from one major version to the next should always use the USB guide in the Step by Step tab — it is the most reliable method.

Note

32GB Chromebooks and Minis need their own update flow — see Small Storage Devices.

Install curriculum, apps, and languages

Curriculum and components: apply them with the update guides above; the docs curriculum installs with tl-curriculum-install docs (see Installing Local Patches).
Free up space: the “Manage Components” tool (tl-comp-manage) removes old Btrfs Snapshots and unused components — see Using the Computer.
Games: Installing Games copies bundles from another computer on the LAN.
The code curriculum: how TechLit teaches programming — students read written instructions and turn them into working programs. The languages it uses (Python, JavaScript, and friends) are managed with asdf: Setting Up Programming Languages.

Healthy-classroom checklist

One server only — exactly one computer has Role server, and it is wired with Wi-Fi switched off.
Clients configured — every computer configured as a client shows Role client and the right Wi-Fi name.
Address server running — on the server, rsv status dhcpd4 shows run.
Network visible — client computers can see the Wi-Fi network and connect to it.
code languages work (if installed) — asdf current lists the languages, and python --version runs without errors.

When something goes wrong

Symptom	Go to
No Wi-Fi or cabling	Network troubleshooting
Will not boot	Hardware & Device FAQ
Setup or USB failed	Troubleshooting Provisioning
Slow, disk full, TTY	Software & System FAQ
Router or DHCP	Router Configuration
Update files missing	How to Get Update Files

Command quick-reference

Command	What it does
`tl-sys-configure`	Set computer name, Role, and Wi-Fi name
`tl-comp-manage`	View components, free up disk space
`tl-comp-update`	Install component updates from USB
`tl-comp-pull <name> <remote>`	Copy a component from a source computer
`tl-comp-latest <name>`	Show the newest version available
`tl-archive-install <name>`	Install a downloaded component
`tl-curriculum-install <subject>`	Install the curriculum
`tl-usb-prepare /dev/sdX`	Create an installer USB (erases it)
`tl-hw-prepare /dev/sdX tl-xxxx`	Install the system (erases the drive)
`tl-hw-update-desktop /dev/sdX`	Update the system, keeping the data
`lsblk`	List connected drives
`rsv status dhcpd4`	Check the address server (DHCP)
`asdf current`	List the languages for the `code` curriculum