# TechLit System Help

> Documentation for TechLit System
> Base URL: https://help.techlitafrica.org/

This file contains the full content of every non-draft page on this site,
formatted for LLM consumption. Use this as context to answer questions about
the TechLit system, classroom setup, updates, troubleshooting, and more.

---

## About TechLit Africa

TechLit Africa sets up and maintains computer labs in Kenyan schools. Each
classroom runs the TechLit OS — a custom Linux distribution (Artix-based) with
a managed software stack. Teachers and students use every classroom computer;
admin tasks are performed via dedicated admin scripts.

The system is deployed and updated using USB drives. Each classroom assigns one
computer the **server** role and the remaining computers the **client** role.
The server connects by Ethernet to the router; these roles describe network
functions, not who may use a computer. Software is distributed in pre-packaged
"components" (admin, curriculum, control, type) that are versioned and updated
together.

Key concepts:
- **Admin Mode (TTY2):** The expert-mode screen for teachers to run sysadmin
  tasks like updating software or fixing system settings.
- **Components:** Pre-configured software modules bundled into single packages
  for fast lab management. Main components: `admin`, `curriculum`, `control`,
  `type`.
- **Provisioning:** Setting up a computer for the first time with the TechLit OS.
- **Recovery:** Booting from a USB drive to fix problems or install updates.
- **Btrfs Snapshots:** Saved versions of system files used for safe updates
  and rollbacks.
- **Server / Client roles:** One computer is the server and the others are
  clients. Every computer, including the server, is available for student use.
- **asdf:** The version manager used for programming languages (Python,
  JavaScript, Java, etc.) taught in curriculum.

---

## Glossary

- **Admin Mode (TTY2):** The 'Admin Mode (TTY2)' screen for teachers. Use this to perform sysadmin tasks like updating software or fixing system settings.
- **Btrfs Snapshots:** A saved version of the computer's system files. This is how TechLit safely updates and develops software without losing data.
- **Ethernet Cable:** The grey / white, or blue cables (Ethernet) that connect computers directly to the router.
- **Target Drive:** The specific disk inside a computer where you want to install or update the TechLit OS (e.g., /dev/sda).
- **Role:** This describes how a computer acts on the network. A computer can be a Server or a Client.
- **SSID:** The name of your Wi-Fi network that client computers connect to.
- **Provisioning:** Setting up a computer for the first time with the TechLit system.
- **DNS:** The system that turns website names into addresses the computer can understand.
- **component:** A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.
- **recovery:** Booting a computer from a USB drive to fix problems or install Updates.

---

## Schools

Amagoro, Bahakwenu, Barina, Calvary, Chepyuan, Egu, Elite, Fuyele, Kapkures, Kipkenyo, Lekuruki, Little Lambs, Logiri, Magale, Menengai, Mgalani, Mirera (Emacs), Mirera (Vim), Mokombet, Murengeti, Muruai, Ndatho, Nyatieko, Ogur, Pendo, Raya, SNS (Emacs), SNS (Vim), Salama, Senty, Taru, Zawadi

---

## How-To Guides


Your central resource for installing, managing, and fixing TechLit classroom computers. Choose a section below or use the search bar to find what you need.

---

<CardGrid>
  <LinkCard title="Using the Computer" href="/docs/desktop/" description="Manage system settings, apps, and day-to-day desktop tasks." />
  <LinkCard title="Network &amp; Wi-Fi" href="/docs/network/" description="Set up and fix the classroom network and Wi-Fi connections." />
  <LinkCard title="Updates" href="/docs/updating/" description="How to get the latest components from the internet and install it on your computers." />
  <LinkCard title="Setup &amp; Repair (USB)" href="/docs/device_provision/" description="Steps for setting up a new computer or fixing one that will not start." />
  <LinkCard title="Advanced Tools &amp; Networking" href="/docs/advanced/" description="Guides for complex tasks like fixing routers or creating installer USBs." />
  <LinkCard title="Common Questions" href="/docs/faq/" description="Find quick answers to common issues and hardware-specific tips." />
</CardGrid>

### Set Up Your Classroom from Scratch

> URL: https://help.techlitafrica.org/docs/start/

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 and updating from Bastion. Those guides say so.

**Only here for one task?** Jump straight to it:

- Update working computers: [Updates](/docs/updating/)
- Fix Wi-Fi or cables: [Network troubleshooting](/docs/network/#fixing-network-problems)
- Set up languages for the `code` curriculum: [Setting Up Programming
  Languages](/docs/desktop/languages/)
- Add games: [Installing Games](/docs/desktop/#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 <abbr title="The grey / white, or blue cables (Ethernet) that connect computers directly to the router.">Ethernet Cable</abbr>s (the grey or
  white cables)
- A TechLit installer USB. If you don't have one, follow
  [Create an Installer USB](/docs/advanced/#create-or-re-provision-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**
>
> 1. Only **one** computer may have the <abbr title="This describes how a computer acts on the network. A computer can be a Server or a Client.">Role</abbr> `server`.
> 2. The server must be connected by cable, never over Wi-Fi.

## Connect the hardware

<Tabs>
<TabItem label="Step by Step">
<Steps>
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.
   - **2 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.

</Steps>
</TabItem>
<TabItem label="More Detail">

- Wire everything you can; Wi-Fi is the fallback, not the default.
- The server must never use Wi-Fi. After setup, switch its Wi-Fi off.

</TabItem>
</Tabs>

## Set the network roles

Every computer gets a <abbr title="This describes how a computer acts on the network. A computer can be a Server or a Client.">Role</abbr> (`server` or `client`), set
with the `tl-sys-configure` tool (logged in as `admin`).

<Tabs>
<TabItem label="Step by Step">
<Steps>
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:

   1. Set the **Role** to `client`.
   2. Set the **Wi-Fi Name** (<abbr title="The name of your Wi-Fi network that client computers connect to.">SSID</abbr>) 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 at the bottom right of the screen, next to the volume and
   battery icons.

</Steps>
</TabItem>
<TabItem label="More Detail">

- `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.
- Check the address server (DHCP) is running:

  ```bash
  rsv status dhcpd4
  ```

  It should show `run`. If it shows `down`, restart it with
  `sudo rsv restart dhcpd4`.
- **2 routers?** Split the load: give half the clients one SSID and
  half the other.
- Re-check that **no other computer** is set to `server`. 2 servers
  break the whole network.

</TabItem>
</Tabs>

For cable diagrams and the full setup, see the
[Network & Wi-Fi](/docs/network/).

## 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](/docs/advanced/#create-or-re-provision-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.

<Tabs>
<TabItem label="Step by Step">
<Steps>
1. **Boot from the USB**

   Restart the computer and boot from the TechLit USB drive.

2. **Identify the internal drive**

   ```bash
   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
   <abbr title="The specific disk inside a computer where you want to install or update the TechLit OS (e.g., /dev/sda).">Target Drive</abbr>.

3. **Install the system**

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

   ```bash
   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.

</Steps>
</TabItem>
<TabItem label="More Detail">

2 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 26.6.0`.

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

```bash
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](/docs/device_provision/#troubleshooting-provisioning).

</TabItem>
</Tabs>

> [!WARNING] **Small devices (under 32GB)**
>
> Do not use this method on these devices. Follow
> [Small Storage Devices](/docs/updating/low-storage-devices/) instead.

## Update the classroom

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

<Tabs>
<TabItem label="Step by Step">

For standard desktop computers, update from a prepared USB drive. See
[Standard Desktop Computers](/docs/updating/#standard-desktop-computers):

1. Plug the USB in and open **"Update Components"** (or run
   `tl-comp-update`).
2. Choose **Update → Update Desktop (Using USB)**.
3. Pick your USB drive and wait for it to finish, then unplug the USB.
4. Reboot when prompted.

</TabItem>
<TabItem label="More Detail">

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

1. Get the update files onto one machine: bring them in on a USB drive
   or use a computer that already has them ([Get and Install
   Updates](/docs/updating/get-updates/)).
2. Copy them to the computer that needs them:

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

   The command changes with the component. Check the rule in [Get and Install
   Updates](/docs/updating/get-updates/).

3. Apply them with
   [Installing Local Updates](/docs/updating/get-updates/#installing-local-updates):
   `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.

</TabItem>
</Tabs>

> [!NOTE]
>
> A small disk needs its own update flow. The disk size decides the component
> and the method, not the computer model. Check the size with `lsblk`, then
> follow [Small Storage Devices](/docs/updating/low-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](/docs/updating/get-updates/#installing-local-updates)).
- **Free up space:** the **"Manage Components"** tool
  (`tl-comp-manage`) removes old <abbr title="A saved version of the computer's system files. This is how TechLit safely updates and develops software without losing data.">Btrfs Snapshots</abbr> and
  unused components. See [Using the Computer](/docs/desktop/).
- **Games:** [Installing Games](/docs/desktop/#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](/docs/desktop/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](/docs/network/#fixing-network-problems) |
| Will not boot | [Hardware & Device FAQ](/docs/faq/#hardware--device-faq) |
| Setup or USB failed | [Troubleshooting Provisioning](/docs/device_provision/#troubleshooting-provisioning) |
| Slow, disk full, TTY | [Software & System FAQ](/docs/faq/#software--system-faq) |
| Router or DHCP | [Router Configuration](/docs/advanced/router/) |
| Update files missing | [Get and Install Updates](/docs/updating/get-updates/) |

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

---

### Network & Wi-Fi

> URL: https://help.techlitafrica.org/docs/network/

This guide explains how to set up the local network in your classroom. One
computer acts as a **server**; the others act as **clients**. All computers,
including the server, are used by students.

> [!NOTE]
> `server` and `client` describe network roles, not who uses a computer.
>
> [!WARNING] **CRITICAL SETUP RULES**
>
> 1. **ONE SERVER ONLY:** You can only have **one** computer set as a `server` on the network. Multiple servers will cause the network to fail.
> 2. **SERVER USES CABLE:** The server machine **must not** use Wi-Fi. It must connect to the router using a <abbr title="The grey / white, or blue cables (Ethernet) that connect computers directly to the router.">Ethernet Cable</abbr>.

---

## Phase 1: Setting up Cables & Hardware

This part involves connecting the server and routers together.

<Steps>
1. **Choose and Connect the Server**

   Select one computer to be the **server**. This should be your fastest machine with an Ethernet port. Connect this server directly to your main router using a <abbr title="The grey / white, or blue cables (Ethernet) that connect computers directly to the router.">Ethernet Cable</abbr>.

2. **Place and Connect Routers**

   - **One Router:** Place it in the middle of the room for best Wi-Fi signal.
   - **2 routers:** If you have a second router, connect it to the first one with a cable. Place them as far apart as possible.

3. **Connect Other Computers with Cables (Best)**

   Whenever possible, connect the other computers to a router using a
   <abbr title="The grey / white, or blue cables (Ethernet) that connect computers directly to the router.">Ethernet Cable</abbr>. This is much faster and more reliable than Wi-Fi.

</Steps>

---

## Phase 2: Software Setup

This part involves setting up the <abbr title="This describes how a computer acts on the network. A computer can be a Server or a Client.">Role</abbr> on each computer using the `tl-sys-configure` tool.

<Steps>
1. **Set up the Server**

   On the main server machine, run `tl-sys-configure` and set its <abbr title="This describes how a computer acts on the network. A computer can be a Server or a Client.">Role</abbr> to `server`.

   > [!CAUTION]
   > Double-check that no other computer is set as a `server`.

2. **Set up the Clients**

   On each computer configured as a client, run `tl-sys-configure` and do the
   following:

   1. **Set the Role**: Set the <abbr title="This describes how a computer acts on the network. A computer can be a Server or a Client.">Role</abbr> to `client`.
   2. **Set the Wi-Fi Name**: Set the <abbr title="The name of your Wi-Fi network that client computers connect to.">SSID</abbr> (Wi-Fi name) to match the network you want clients to use.

   :::tip[Tip: Spreading the Load]
   If you have multiple routers, try to spread clients across them.

   - **One Router:** All clients connect to the same Wi-Fi name (<abbr title="The name of your Wi-Fi network that client computers connect to.">SSID</abbr>).
   - **2 routers:** Set half the clients to the first Wi-Fi name, and half to the second Wi-Fi name.
   :::

3. **Turn off Wi-Fi on Wired Machines**

   On any computer connected with a cable (including the server), turn off the Wi-Fi. You can use the network icon at the bottom right of the screen, next to the volume and battery icons, to do this.

   > [!IMPORTANT]
   > Always make sure the server has Wi-Fi turned off.

</Steps>

---

## Fixing Network Problems

If your classroom network is not working, follow these steps to fix common issues. If you still have trouble, recheck [Phase 1](#phase-1-setting-up-cables--hardware) and [Phase 2](#phase-2-software-setup) to ensure everything is connected correctly.

---

### Quick Check List

Work through these checks in order.

<Steps>
1. **Restart Devices**

   Power off your routers and the server (main) computer, then turn them back on.

2. **Check Physical Connections**

   - Ensure the **grey or white network cables** are plugged in firmly at both ends.
   - Check the **Server** machine has a solid cable connection to the main router.
   - Look at the router lights to ensure they are on and blinking.

3. **Ensure a Single Server**

   Check that **only one** computer on the network is set as the `server` in `tl-sys-configure`. Having 2 servers will cause the network to fail.

4. **Check Client Configuration**

   On a computer configured as a client that cannot connect, run
   `tl-sys-configure` and check:

   1. **Role**: Set to `client`.
   2. **Wi-Fi Name**: Set to the correct network name.

5. **Check Server Status**

   On the **Server** computer, check if the "address server" (DHCP) is running. Open the terminal and type:

   ```bash
   rsv status dhcpd4
   ```

   > **Expected Result:** The status should show `run`. If it shows `down`, type `sudo rsv restart dhcpd4`.

</Steps>

---

### Common Problems & Solutions

| Problem                  | Quick Fix                                                                             |
| :----------------------- | :------------------------------------------------------------------------------------ |
| **No Wi-Fi visible**     | Check if the Server and Router are powered on and the Server's own Wi-Fi is disabled. |
| **"Limited Connection"** | This usually means the address server is not working. See Step 5 above.               |
| **Very Slow Network**    | Too many computers on Wi-Fi. Connect more machines using grey/white cables.           |

---

**Next:** [Update the computers](/docs/updating/). If the network stops working again, use [Fixing Network Problems](#fixing-network-problems) above.

---

### Setup & Repair (USB)

> URL: https://help.techlitafrica.org/docs/device_provision/

---

## Setting Up or Recovering a Computer

A new computer, or one that will not start? The USB Installer handles both
a fresh installation and a wipe-and-reinstall of an existing machine.

<LinkCard title="Install or Update the System" href="#install-or-update-the-system" description="Set up a new computer, or fix one that will not start, using the USB installer." />

---

## Install or Update the System

After booting from the USB, you will use commands to install or update the TechLit OS on the computer's internal drive.

> [!WARNING] **Devices under 32GB**
> Do not use this guide on these devices. Follow [Small Storage Devices](/docs/updating/low-storage-devices/) instead.

---

<Steps>
1. **Identify the Internal Drive**

   Run this command to see all the storage drives connected to your computer:

   ```bash
   lsblk
   ```

   > **How to find it:** Look for the main drive, which is usually much larger than your USB drive.
   > Common names are `/dev/sda`, `/dev/nvme0n1`, or `/dev/mmcblk0`. This will be your **<abbr title="The specific disk inside a computer where you want to install or update the TechLit OS (e.g., /dev/sda).">Target Drive</abbr>**.

   ---

2. **Choose Your Action**

   Choose one of the 2 actions below.

   ### Option A: <abbr title="Setting up a computer for the first time with the TechLit system.">Provisioning</abbr> a New Computer (`tl-hw-prepare`)

   Use this command for a **new computer** or to completely **wipe and reinstall** an existing one.

   > [!CAUTION]
   > This command will permanently erase all data on the target drive.

   ```bash
   # Replace /dev/sdX with your drive and tl-xxxx with the tag
   tl-hw-prepare /dev/sdX tl-xxxx
   ```

   ### Option B: Update Existing System (`tl-hw-update-desktop`)

   Use this command to **update** an existing TechLit computer without wiping its data.

   ```bash
   # Replace /dev/sdX with your drive
   tl-hw-update-desktop /dev/sdX
   ```

   ---

3. **Finish & Reboot**

   Once the script finishes, you will see a success message.

   ![Update Complete](done.jpg)

   Reboot the computer by typing `reboot` and pressing Enter.

   > [!NOTE]
   > Unplug the USB drive immediately after the computer restarts to prevent it from booting back into the installer.

</Steps>

### Examples

- **Install** on a computer with drive `/dev/nvme0n1` and tag `tl-0606`:

  ```bash
  tl-hw-prepare /dev/nvme0n1 tl-0606
  ```

- **Install** and set the Wi-Fi name at the same time:

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

- **Update** a computer with drive `/dev/sda`:

  ```bash
  tl-hw-update-desktop /dev/sda
  ```

- **Update** to a specific version on the USB:

  ```bash
  tl-hw-update-desktop /dev/sda 26.6.0
  ```

---

## When Something Goes Wrong

If the installer itself is misbehaving (the USB will not boot, or a
command failed), these are the fixes.

## Troubleshooting Provisioning

This guide helps you solve common issues that can occur during the device provisioning process.

---

## Problem: The USB drive won't boot

This can happen in a few ways: the computer boots to the old OS, it gets stuck in a loop, or it shows an error like "Selected boot device failed."


1. **Try a different USB port.** Sometimes switching from a USB 2.0 (black) to a USB 3.0 (blue) port, or vice-versa, can solve the problem.
2. **Check the BIOS/UEFI settings.** You may need to enter the full BIOS setup menu to make changes.
   - **Accessing BIOS Setup:** The key is usually `F1`, `F2`, `F10`, or `DEL`.
   - **Enable USB Boot:** Look for an option to "Enable USB Boot" and make sure it is turned on.
   - **Disable Secure Boot:** If you see an option for "Secure Boot", try disabling it.
   - **Switch Boot Mode:** Try switching the boot mode from `UEFI` to `Legacy/CSM` or vice-versa.
   - **Manually Add Boot Option:** Some BIOS versions require you to manually add the USB drive as a trusted boot option. Look for a "Boot Sequence" or "Add Boot Option" menu. The file to select on the USB is usually `\\EFI\\BOOT\\BOOTX64.EFI`.
   ![An example of a Dell BIOS Menu](dell_bios.jpg)

---

## Problem: I ran the command with the wrong information

If you made a mistake while running `tl-hw-prepare` or `tl-hw-update-desktop`, you can correct it after the install finishes.

- **Wrong Tag, Wi-Fi Name, or Password:** Don't worry. Let the installation finish. Once you boot into the desktop, you can easily fix these settings using the `tl-sys-configure` tool.

---

## Problem: I'm still stuck

If you've tried the steps above and are still having issues, you can ask for help.

To get the best help, provide as much information as possible:
1. **Computer Details:** The brand and model of the computer (e.g., "HP Elitebook 840 G3").
2. **Commands You Ran:** The exact command you used (e.g., `tl-hw-prepare /dev/sda tl-1234`).
3. **Observed Behavior:** What exactly happened? Note any error messages you saw on the screen or describe where the process got stuck.



---

:::note
Previously, this was a standard update method. For routine updates on a working computer, see the **[Updating Guide](/docs/updating/)** instead.
:::

---

### Common Questions

> URL: https://help.techlitafrica.org/docs/faq/

This section has answers to common questions about using TechLit computers.

## Software & System FAQ

### My computer is slow/laggy after updating

Switch or enable a GPU hacks in
[reconfigure](/docs/desktop/#changing-system-settings-tl-sys-configure)

### Login as admin

Log in as the `admin` user when a step needs administrator access.

```bash
su admin
# pass: <admin password>

# if you want clean env vars
su - admin
su -l admin
```

### Component not installed

Create the missing component directory under `/srv/`. See
[Admin Scripts](/docs/desktop/#admin-scripts) for the `tl-comp-*` component tools.

```bash
mkdir /srv/component_name
```

### How do I switch between the graphical desktop and a TTY?

You can switch to {{< term "Admin Mode (TTY2)" >}} if the graphical desktop is frozen or for admin tasks like updating.

- **To switch to TTY2:**
    - On most computers: <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>F2</kbd>
    - On Apple computers: <kbd>CMD</kbd> + <kbd>Option</kbd> + <kbd>F2</kbd>
    - In rare cases: <kbd>FN</kbd> + <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>F2</kbd>
    - As admin: `sudo chvt 2`

> [!TIP]
> If the key combinations don't work, try connecting an external USB keyboard.
> Sometimes, a built-in keyboard might be broken or unresponsive.

- **To switch back to the graphical desktop (TTY1):**
    - Exit fbterm with `exit` then use <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>F1</kbd>.
    - You can also use <kbd>Super</kbd> + <kbd>Alt</kbd> + <kbd>←</kbd>.
    - As admin: `sudo chvt 1`.

### My computer hostname is mismatched with the tag

If the computer's name does not match its tag, set the correct name with the
[Settings Menu (tl-sys-configure)](/docs/desktop/#changing-system-settings-tl-sys-configure).

### Fix storage issues ("Disk Full" Error)

Use [tl-comp-manage](/docs/desktop/#managing-apps--storage-tl-comp-manage)
to remove old {{< term "Btrfs Snapshots" >}} and free up space.

## Hardware & Device FAQ

### My computer fails to boot or drops to a shell

If your computer fails to boot properly and drops you into a command-line shell (often called a "rootfs shell"),
it may be because the bootloader is broken or misconfigured.

To fix this, you must first boot from your TechLit USB drive. Once you have booted into the USB environment, you have 2 options:

1. **Reinstall the bootloader:**
   This is the quickest method. Open a terminal and run the following command:

   ```bash
   sudo tl-hw-update-bootloader /dev/sdX
   ```

   > [!NOTE] **Device Drive**
   > Replace `/dev/sdX` with the correct device name for your computer's **{{< term "Target Drive" >}}**
   > (e.g., `/dev/sda`). Use `lsblk` to identify it.

2. **Run a full desktop update:**

`tl-hw-update-desktop`. See the [updating
guide](/docs/device_provision/#option-b-update-existing-system-tl-hw-update-desktop).

### How do I identify my USB drive?

Run `lsblk` to list the connected drives, then match the USB by its size.

```bash
lsblk
```

1. Check by Storage Size

   > The USB drive's total size is a good indicator.
   > It will almost always be significantly smaller than your
   > computer's internal storage (hard drive or SSD).

2. Check by Mount Points

- **On the TechLit Desktop OS:** The main system partition is typically mounted at `/`. Your USB drive will likely not be mounted, or mounted elsewhere.
- **In TechLit ISO (Recovery Mode):** The system boots from the USB, so its partitions will be mounted on key system directories:
    - The **4th partition** (e.g., `/dev/sdb4`) is mounted at `/srv`.
    - The **3rd partition** (e.g., `/dev/sdb3`) is mounted at `/`.

### How do I mount my USB drive?

Identify the drive first, then mount its 4th partition to `/mnt`.

```bash
# Identify the USB drive (say usb is /dev/sda)
lsblk

# Mount the 4th partition of the USB drive
sudo mount /dev/sda4 /mnt
```

### Wi-Fi Issues

#### How do I stop the firewall temporarily?

Stop the firewall only while you need it off, then start it again.

> [!CAUTION] **Security Risk**
> Only disable if necessary. Re-enable immediately after.

```bash
rsv stop nftables # Stop the firewall
rsv start nftables # reactivate the firewall
```

#### I am unable to turn on my Wi-Fi

Work through these checks in order:

- Run `rfkill list` to see all your network devices.
- If your card is listed as soft blocked, run `sudo rfkill unblock wifi`
  to turn it on.
- If it is hard blocked, look for a hardware switch on your computer
  and turn it on.
- If none of these work, try a different Wi-Fi option in the
  [Settings Menu (tl-sys-configure)](/docs/desktop/#changing-system-settings-tl-sys-configure).

### Device-Specific Guides

#### Dell

{{% details title="Dell boot fixes" closed="true" %}}

This section provides solutions for common issues encountered with Dell

##### **Invalid Partition Table** Error on Boot

1. Switch to UEFI Boot Mode

   - Restart the computer and press `F2` or `F12` to enter BIOS setup.
   - Navigate to **General > Boot Sequence**.
   - Change the boot mode from **Legacy** to **UEFI**.
   - Save changes and exit BIOS.

2. Press Enter to ignore the warning and proceed booting.

##### USB Boot Failure

If you encounter the error **"Selected boot device failed.
Press any key to reboot the system,"** follow these steps:

1. **Try a different USB port.** A simple port change can often resolve the issue.
2. **Manually add the boot option in BIOS:**
   - Restart the computer and press `F2` or `F12` to enter BIOS setup.
   - Navigate to **General > Boot Sequence**.
     ![Add boot](../../../assets/faq/dell_xps_add.png "Boot list")
   - Click **Add Boot Option**.
   - Select your USB device and navigate to the `\EFI\BOOT\BOOTX64.EFI` file.
     ![Boot img](../../../assets/faq/dell_xps_boot_img.jpg "Boot list")
   - Save your changes and exit BIOS. You should now be able to select the USB drive from the boot menu.
     ![Boot list](../../../assets/faq/dell_xps_boot_list.jpg "Boot list")

##### USB 3.x Drive Not Detected

If your system fails to detect a USB 3.x drive, you may need to adjust the boot mode settings in the BIOS.

1. Enter BIOS setup by pressing `F2` or `F12` during startup.
2. Locate the boot settings and change the boot mode from **BIOS/Legacy** to **UEFI**.
   {{% /details %}}

#### HP

{{% details title="HP boot fixes" closed="true" %}}

This section provides solutions for common issues encountered with HP devices.

##### USB 3.x Drive Not Detected in Boot Menu

Some older HP models may not automatically detect a bootable USB 3.x drive. Here are 2 methods to resolve this:

###### 1. Switch Boot Modes

Changing the boot mode in the BIOS can often force the system to recognize the USB drive.

1. Enter the BIOS setup (usually by pressing `F10` or `ESC` during startup).
2. Locate the boot options or system configuration.
3. Change the boot mode from **UEFI** to **Legacy**, or from **Legacy** to **UEFI**.
4. Save the changes and restart. See if the USB drive appears in the boot menu.

###### 2. Boot From EFI File

If switching boot modes doesn't work, you can manually select the boot file. This is the most reliable method.

1. Enter the BIOS setup.
2. Find the boot menu and look for an option like **"Boot From EFI File"** or **"Select UEFI File as Trusted for Executing"**.
3. Navigate to your USB device and select the `\EFI\BOOT\BOOTX64.EFI` file.
4. Save the configuration and restart. The USB drive should now be a bootable option.

{{% /details %}}

---


### Using the Computer


<details>
<summary>What is this section about?</summary>

This section covers day-to-day tasks on a TechLit computer, from changing settings to managing apps and games.

</details>

---

## Changing System Settings (`tl-sys-configure`)

This is the main tool for setting up a computer's name and its role in the classroom.

:::note
Open this tool by typing `tl-sys-configure` in the terminal (logged in as admin).
:::

<Card title="Settings Menu">
![Settings Menu](./reconfigure_terminal.jpg)

Use arrow keys to move, Space to select, and Enter to finish.
</Card>

<details>
<summary>**What you can do here**</summary>

- **Set Role**: Make the computer a `server` (main) or a `client` (network
  role).
- **Wi-Fi Setup**: Set the name of the classroom Wi-Fi network.
- **Computer Name**: Give the computer a unique name (like `tl-1234`).
- **Fix Hardware**: Turn on special fixes for older computers.

</details>

---

## Managing Apps & Storage (`tl-comp-manage`)

Use this tool to see which apps are installed and to free up disk space by removing old files.

<Card title="Manage Components">
![Manage Components](comp-manage-home.png)

Search for 'Manage Components' in the menu to start.
</Card>

<details>
<summary>**How to use this tool**</summary>

### **Check Space**

- See a list of all installed parts and how much space they use.
- Remove old parts or Btrfs Snapshots to get more free space.

</details>

---

## Updating components (`tl-comp-update`)

Use this tool to update the computer's software using a USB drive.

<Card title="Update Components">
![Update Components](/images/components-updater.png)

Search for 'Update Components' in the menu to start.
</Card>

<details>
<summary>**How to use this tool**</summary>

### **USB Updates**

- Update apps and tools from a USB drive.
- Perform a full update of the computer system.

</details>

---

## Installing Games

TechLit computers support adding games and other software as "package bundles".
These bundles are managed similarly to other system components and can be
pulled from the network and installed locally.

<Asciinema file="casts/games.cast" theme="dracula" speed="1.5" autoplay="true" loop="true" markers="0:Pulling,12.2:Installing" />

---

### Installing a Game Bundle

Installing a game involves pulling the bundle files to the computer and
then running the installation command provided by the tool.

<Steps>
1. **Pull the Bundle**

   First, ensure the game bundle is available on your computer.
   You can pull it from the internet (Bastion) or another computer on the network (LAN).

   **From the Internet (Bastion):**

   ```bash
   # Example for SuperTux
   tl-comp-pull supertux-bundle https://bastion
   ```

   **From a Local Computer (LAN):**

   ```bash
   # Replace 'tl-1234' with the hostname of the source computer
   tl-comp-pull supertux-bundle tl-1234.local
   ```

2. **Run the Installation Command**

   Once the bundle is pulled, the `tl-comp-pull` command will display the specific
   instructions for installing it. It usually involves running a command like this:

   ```bash
   # Copy the exact command from your terminal output
   sudo pacman -U /srv/packages/bundle-name/*.pkg.tar.zst
   ```

</Steps>

---

### Uninstalling a Game

If you need to remove a game, you have several options depending on
whether you want to remove just the game or revert recent system changes.

#### Option 1: Using the Package Manager

The recommended way to remove a specific game package is to use
the package manager.

```bash
# Replace 'game-name' with the actual package name (e.g., supertuxkart)
sudo pacman -Rs game-name
```

#### Option 2: System Restore

You can also use TechLit's built-in tools to revert the system to its
previous state.

- **Restore Snapshot:** `tl-img-restore`
- **Reconfigure System:** `tl-sys-configure`

---

## Admin Scripts

<details>
<summary>What are admin scripts?</summary>

These are the scripts you will be using to maintain your
TechLit System (fresh install, upgrade, reinstall, etc.)

:::note
- __Run as admin__: You need to be admin user to run the script.
- __Basic Usage__: To run a script, use the following format:
  `tl-group-command` parameters (e.g., `tl-hw-prepare /dev/sdb tl-2054`)
- __HELP__: Run the command without any arguments to print a quick usage.
- __Environment Variables__: Customize behavior with environment variables like:
  `WIFI_NAME='My Network' tl-hw-prepare /dev/sda tl-2054`
:::

### Script format

<details>
<summary>How are scripts named?</summary>

The scripts follow a naming convention to make them easy to identify and use

- All admin scripts follow a consistent format: `tl-*-*`.
- Each script begins with the __prefix__ `tl-`.
- The second part represents the __group__ of commands it belongs
  to (e.g., `hw`, `img`, `comp`, `sys`, or `usb`).
- Finally, the third part specifies the specific __action__ or command
  within that group (e.g., `prepare`, `update`, etc.).
</details>

### Groups of commands

<details>
<summary>What are the command groups?</summary>

The admin scripts are organized into distinct groups, each serving a specific purpose.
</details>

<Tabs>
<TabItem label="Hardware">

#### `tl-hw-*`

<details>
<summary>Hardware related commands</summary>

Hardware related commands (partitioning, installing components, updating bootloaders).

- `tl-hw-prepare`: Creates partitions and installs components for the TechLit system.

- Takes a hard drive and a tag as parameters.
- Example `tl-hw-prepare /dev/sdX tl-2054`

- `tl-hw-update-desktop`: Unpacks the TechLit system archive into an already-provisioned desktop system on `/dev/sdX`.
  Takes a hard drive and an optional version as parameters. Example: `tl-hw-update-desktop /dev/sdX`
- `tl-hw-update-bootloader`: Installs and configures the bootloader on `/dev/sdx`.
- `tl-hw-chroot-desktop`: Mounts the required partitions and chroots into the TechLit system on `/dev/sdx`.
</details>
</TabItem>

<TabItem label="Image">

#### `tl-img-*`

<details>
<summary>Desktop image management</summary>

Desktop image management (creating snapshots, packing/unpacking, restoring).

1. `tl-img-save`: Creates a new snapshot of the TechLit system hosted at `/var/btrfs/snapshots`.
2. `tl-img-pack`: Creates a new clone-able archive of the TechLit system.
3. `tl-img-unpack`: Unpacks a desktop archive into the TechLit system.
4. `tl-img-restore`: Restores a desktop snapshot of the TechLit system.
</details>
</TabItem>

<TabItem label="Component">

#### `tl-comp-*`

<details>
<summary>Component management</summary>

Component management (pulling, pushing, and syncing components).

- All the components are hosted in `/srv/$component`
- Components include (but not limited to)
  `desktop`, `admin`, `curriculum`, `help` `control`

1. `tl-comp-pull`: Downloads a version of a <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> from `remote`.
2. `tl-comp-push`: Uploads a version of a <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> from `/srv/component/` to `remote`.
3. `tl-comp-sync`: Updates list of local and remote versions for <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr>.
   (This script is called by the other 2 scripts in this group)
</details>
</TabItem>

<TabItem label="System">

#### `tl-sys-*`

<details>
<summary>System configuration</summary>

System configuration (network setup, Driver personalization etc).

1. `tl-sys-configure`: Reconfigures the TechLit system with a new configuration file.
   - The options include: `role`, `hostname`, `wifi_name`, and `wifi_password`
   - The config file is located here `/srv/secure/config.json`
2. `tl-sys-personalize`: Personalizes the system using the values in `config.json`.
3. `tl-sys-anonymize`: Removes sensitive data and the custom configuration from the TechLit system.
</details>
</TabItem>

<TabItem label="USB">
#### `tl-usb-*`

<details>
<summary>USB drive tasks</summary>

USB drive tasks (creating installer USBs, updating components).

- `tl-usb-prepare`: Creates a TechLit installer USB on `/dev/sdx` and installs components on it.
- `tl-usb-update-components`: Copies updated TechLit components on the USB.
- `tl-usb-update-recovery`: Updates iso partition with a new recovery iso.
- `tl-usb-update-bootloader`: Installs or updates and configures the bootloader for the USB.
</details>
</TabItem>
</Tabs>

### Examples

<details>
<summary>See command examples</summary>


Some examples of some common command usage

#### Install

- A TechLit system for the first time on a computer
  with a hard drive `/dev/sda` and tag `tl-2054`

```bash
tl-hw-prepare /dev/sda tl-2054
```

- With environment variables

```bash
WIFI_NAME="TechLit Vim" tl-hw-prepare /dev/sda tl-2054
```

#### Update

- A TechLit system from a desktop image hosted in `/dev/sda`

```bash
tl-hw-update-desktop /dev/sda
```

#### Reconfigure

- A TechLit system first time after preparing

```bash
tl-sys-configure
```

#### Fix Bootloader

- On a TechLit Computer unable to boot because of bootloader or wrong fstab by
  reinstalling Grub bootloader on a TechLit system installed at `/dev/sda`

```bash
sudo tl-hw-update-bootloader /dev/sda
```

</details>
</details>

---

## More topics

<LinkCard title="Setting Up Programming Languages" href="/docs/desktop/languages/" description="Install and switch the programming languages used in class." />

- **System Updates:** You mostly use the **Update Components** tool for this.
  The method changes if you use a USB drive or the local network. For full steps
  on all update methods, see the [**Update Guide**](/docs/updating/).

### Setting Up Programming Languages

> URL: https://help.techlitafrica.org/docs/desktop/languages/

TechLit computers use [`asdf`](https://asdf-vm.com) to manage the programming
languages you teach, like Python, JavaScript, and Java. Students use them
while learning **`code`**, the TechLit programming curriculum: reading
written instructions and turning them into working programs. `asdf` keeps
every language in its own folder, so two different versions can sit side
by side without breaking each other.

You do not need to install `asdf` itself. The system image already has it, and
it is wired into the `guest` shell. Your job is only to add the languages you
want to teach.

---

## Before You Begin

> [!WARNING] **Admin Setup First**
> 2 things must be done as the `admin` user before you start:
>
> 1. **Stop the firewall**. The school firewall blocks most downloads, so
>    language installs fail while it is running:
>    ```bash
>    rsv stop nftables
>    ```
> 2. **Mount your USB drive** (needed for the USB methods). Plug it in,
>    identify it with `lsblk`, and mount the 4th partition to `/mnt`:
>    ```bash
>    lsblk
>    sudo mount /dev/sda4 /mnt
>    ```
>
> Everything else in this guide runs as the `guest` user. When you are
> finished, restart the firewall as `admin` with `rsv start nftables`.

---

## Method 1: USB Pre-installed (Easiest)

If you have a USB drive with `asdf.tar.gz` on it, use this method. The tarball
already contains the plugins and language versions used in class, so nothing
is downloaded from the internet.

<Steps>
1. **Copy the Tarball from the USB**

   ```bash
   # The USB drive is mounted at /mnt (see Before You Begin)
   cp /mnt/asdf.tar.gz /srv/guest/
   ```

2. **Unpack It**

   ```bash
   # This creates the /srv/guest/asdf folder
   tar -xzf /srv/guest/asdf.tar.gz -C /srv/guest/
   ```

3. **Check the Languages**

   ```bash
   # Make the installed languages visible in your current terminal

   # Show every language and version asdf is managing
   asdf current
   ```

   Run `python --version` (or whichever language you added) to check it works.

</Steps>

---

## Method 2: Individual Install

Use this method to install one language on one computer, directly from the
internet.

<Steps>
1. **Add the Plugin**

   Each language has a plugin. Add the one you need:

   ```bash
   # Example for Python
   asdf plugin add python
   ```

   > [!TIP]
   > If the short name is not found, add the plugin with its full repository URL,
   > e.g. `asdf plugin add python https://github.com/asdf-vm/asdf-python.git`.
   > Every plugin's URL is listed at
   > [github.com/asdf-vm/plugins](https://github.com/asdf-vm/plugins).

2. **Install a Version**

   ```bash
   # See every version available for Python
   asdf list all python

   # Install the one you want (or "latest")
   asdf install python 3.12.3
   ```

3. **Set the Default Version**

   Run this from your home folder so the version applies everywhere for the
   `guest` user:

   ```bash
   cd ~
   asdf set python 3.12.3
   ```

4. **Make Sure the Shims Are on Your PATH**

   The system image already does this for the `guest` shell, but if a command is
   still "not found", add the shims folder to your PATH:

   ```bash
   # For the current terminal session
   ```

</Steps>

---

## Method 3: Fleet Setup

Use this method to set up many computers at once. You prepare the languages
once, then distribute them to the fleet. There are 2 ways to do that.

### Sub-method A: Network Pull

If one computer on the network is already set up, the others can copy from it
directly. Run this on each computer that still needs the languages:

```bash
# Replace 'tl-1234' with the hostname of a computer that is already set up
scp -r tl-1234.local:/srv/guest/asdf /srv/guest/
```

### Sub-method B: Tarball Distribution

Prepare one tarball on a computer that is already set up, then share it on USB
drives the same way as Method 1.

```bash
# On a computer that is already set up
tar -czf asdf-2026-09-04.tar.gz -C /srv/guest asdf
```

Name the tarball with the date you built it (`asdf-2026-09-04.tar.gz`), so it
is always obvious which build is the newest. Keep a `latest.tar.gz` symlink
pointing at the current build, so anything that copies "latest" always gets
the right one:

```bash
ln -sfn asdf-2026-09-04.tar.gz latest.tar.gz
```

> [!TIP] **Delete Old Tarballs**
> Tarballs are large. Once the newest build has been verified on a test
> machine, delete the old dated tarballs from your USB drives and storage
> folders to free up space.

---

## Dependencies & Troubleshooting

- **Read the plugin README first.** Every language plugin needs its own build
  dependencies (compilers, headers, and so on). The plugin's README lists
  exactly what is required. Check it before installing, especially when an
  install fails halfway through.
- **Missing system packages?** The TechLit desktop is Artix Linux. Install missing
  tools and libraries from the AUR with `yay`.
- **Still stuck?** Ask for help. Send the exact command you ran and the full
  error output. A screenshot of the last 20 lines is helpful.

---

## Adding Your Own Languages

The languages above are a starting point, not the limit. `asdf` supports
hundreds of tools and languages, so if you want to teach something new (Rust,
Go, Ruby, or anything else), you can add it yourself.

```bash
# Browse everything asdf can install
asdf plugin list all
```

Once you find your language in the list, follow [Method 2](#method-2-individual-install)
to install it. If you add a language that works well in class, tell the
TechLit team so it can be added to the system image for everyone.

---


### Updates


This section helps you update your TechLit computer to the latest software.

---

## System Updates: Choose Your Device

Most classrooms use **Standard Desktop Computers**. If you have smaller devices (like Chromebooks or Minis), use the Low Storage guide.

<CardGrid>
  <LinkCard title="Small Storage Devices (32GB or Less)" href="/docs/updating/low-storage-devices/" description="Special steps for updating Chromebooks (32GB) or Mini Computers (under 20GB)." />
</CardGrid>

---

## Standard Desktop Computers

> [!WARNING]
> **Devices under 32GB:** Do not use this guide. Follow [Small Storage Devices](/docs/updating/low-storage-devices/) instead.

---

<details>
<summary>Prepare Your USB Drive (if needed)</summary>

Before updating, ensure your USB drive contains the latest <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> files. If it doesn't, you can prepare it on a computer that has the latest updates downloaded.

```bash
# List connected drives to identify your USB
lsblk

# Run the update command (replace /dev/sdX with your USB device)
tl-usb-update-components /dev/sdX
```

</details>

### Update The Computer

<Steps>
1. **Plug in USB and Launch Updater**

   Plug the USB drive into the computer you want to update. Then, search for **"Update Components"** in the application menu and launch it, or run `tl-comp-update` in the terminal.

2. **Select Update Method**

   In the application, select **Update → Update Desktop (Using USB)**.

   ![Select this](/images/components-updater.png "Update Components")

3. **Choose USB Drive**

   Choose your USB drive from the list that appears.

4. **Unplug USB**

   Wait for the process to complete, then unplug the USB drive when prompted to do so.

5. **Reboot**

   The system updates automatically in the background. Once it is finished, press <kbd>Y</kbd> to reboot the computer, or reboot it manually.

</Steps>

---

## Advanced & Patch Updates: Specific Components

If you only need to update a specific part of the software (like the curriculum or a small patch) without using a USB, follow these 2 steps.

<CardGrid>
  <LinkCard title="Get and Install Updates" href="/docs/updating/get-updates/" description="Download files from Bastion or LAN." />
  <LinkCard title="Installing Local Updates" href="/docs/updating/get-updates/#installing-local-updates" description="Apply patches or install components." />
</CardGrid>

:::tip
If you are doing a **major version update** from one major version to the
next, always use the **Standard Desktop Computers** guide above. It is the
most reliable method.
:::

### Small Storage Devices (32GB or Less)

> URL: https://help.techlitafrica.org/docs/updating/low-storage-devices/

This guide is for devices with small disks. The disk size decides the component and the update method.

Check the disk size on the device with `lsblk`:

```bash
lsblk
```

- **Less than 20GB:** the `desktop-mini` component. The device must boot from a USB drive.
- **More than 20GB:** the `desktop` component.

For devices under 32GB, the USB boot may or may not be needed, because they use a different update mechanism.

Common models are a shortcut only. Acer Chromebooks usually have 32GB disks, and Dell and Lenovo Chromebooks usually have 16GB disks. Unusual devices exist, so always check the disk size with `lsblk`.

---

<details>
<summary>Prepare the USB Drive (if needed)</summary>

Before updating, ensure your USB drive contains the correct update files: `desktop-mini` for a device under 20GB, or `desktop` for a larger device.

<Steps>
1. **Check Update Exists Locally**

   On a computer that already has the updates, check the required <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> is available.

   ```bash
   # For devices over 20GB
   tl-comp-latest desktop

   # For devices under 20GB
   tl-comp-latest desktop-mini
   ```

2. **Transfer Files to USB**

   Mount your USB and copy the components to it.

   ```bash
   # Mount the 4th partition of your USB drive
   sudo mount /dev/sdx4 /mnt

   # Create the destination directories
   mkdir -p /mnt/desktop /mnt/admin

   # Transfer the component (replace 'desktop' with 'desktop-mini' if needed)
   rsync -avP /srv/desktop/vX.X.X* /mnt/desktop/
   rsync -avP /srv/admin/vX.X.X* /mnt/admin/
   ```

   > [!NOTE]
   > Replace `vX.X.X` with the actual version number.

</Steps>
</details>

---

## 1. Free Up Space (32GB Devices Only)

If you are updating a **32GB Chromebook**, you **must** free up space before proceeding.

1. Open the application menu and launch the **Manage Components** tool.
2. Delete all existing desktop versions and snapshots. **This is a critical step.**

---

## 2. Install the Update

Once your USB is ready, follow these steps on the target computer.

<Steps>
1. **Boot from the USB Drive**

   Restart the computer and boot from the USB drive.

   - **Chromebooks:** Press `ESC` repeatedly after power-on and select the USB.
   - **Minis:** The boot key varies by manufacturer (usually `F12`, `F11`, or `Esc`).

2. **Execute the Command**

   From the <abbr title="Booting a computer from a USB drive to fix problems or install Updates.">recovery</abbr> environment, run the update command for the internal drive (usually `/dev/mmcblk0` or `/dev/sda`).

   **To Update an existing system:**

   ```bash
   tl-hw-update-desktop /dev/mmcblk0
   ```

   **To Setup a new computer (Fresh Install):**

   ```bash
   tl-hw-prepare /dev/mmcblk0 tl-xxxx
   ```

   > [!TIP]
   > If `tl-hw-update-desktop` fails, use `tl-hw-prepare` instead. This will wipe the drive and start fresh.

3. **Reboot**

   After the command finishes, restart the computer.

   ```bash
   reboot
   ```

</Steps>

---

### Get and Install Updates

> URL: https://help.techlitafrica.org/docs/updating/get-updates/

Before you can update a computer, you need to get the "update files" (the <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> files) onto at least one machine in your lab.

Choose the best method for your classroom below.

---

<Tabs>
<TabItem label="USB Drive (Best)">

## Get Updates from a USB Drive

This is the best way to update many computers without using the internet multiple times.

<Steps>
1. **Plug in the Update USB**

   Insert the TechLit Update USB drive into your computer.

2. **Open the Update Tool**

   Search for **"Update Components"** in the application menu (or run `tl-comp-update` in terminal).

3. **Choose the Update Method**

   Select **"Update from USB"** and follow the on-screen instructions.
</Steps>

</TabItem>
<TabItem label="Internet (Bastion)">

## Get Updates from the Internet (Bastion)

Use this method if you have a good internet connection. You only need to do this once on **one** computer in the lab.

<Steps>
1. **Check Internet Connection**

   Make sure you can connect to the TechLit update server:

   ```bash
   ping bastion.techlitafrica.org
   ```

2. **Download the Updates**

   Run the commands to download the latest updates. You'll need both the `admin` and `desktop` <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> files.

   ```bash
   # Download the admin component
   tl-comp-pull admin https://bastion

   # Download the desktop component
   tl-comp-pull desktop https://bastion
   ```

   :::note
   Small devices use a different component and update method. See [Small Storage Devices](/docs/updating/low-storage-devices/).
   :::

3. **Check the Version**

   Check the update worked:

   ```bash
   tl-comp-latest admin
   tl-comp-latest desktop
   ```
</Steps>

</TabItem>
<TabItem label="Local Network (LAN)">

## Get Updates from Another Computer (LAN)

If one computer in your room already has the update files, you can copy them to other computers over the local Wi-Fi.

<Steps>
1. **Identify the Source Computer**

   Find the name of the computer that already has the files (e.g., `tl-1234`).

2. **Copy the Updates**

   From the computer that **needs** the update, run this command:

   ```bash
   # Copy the 'docs' curriculum from tl-1234
   tl-curriculum-pull docs tl-1234.local
   ```

   The curriculum uses `tl-curriculum-pull`. Every other component, such as
   `desktop` or `admin`, uses `tl-comp-pull` instead.

3. **Check the Result**

   Check that the files were copied correctly:

   ```bash
   tl-comp-latest curriculum docs
   ```
</Steps>

</TabItem>
</Tabs>

---

## Next Step: Install the Updates

Once you have the update files on your computer, you need to **apply** them to your system.

<LinkCard title="Install Local Updates" href="#installing-local-updates" description="Now that you have the files, follow this guide to install the patches or components." />

:::tip
Once you have the files on **one** computer, you can use that machine as the "Source" for the rest of your lab via the **Local Network (LAN)** method.
:::

---

## Installing Local Updates

This guide explains how to install updates that are already on your computer (from the internet, LAN, or USB).

> [!NOTE]
> If you don't have the update files on your computer yet, you must **[get the update files first](/docs/updating/get-updates/)**.

---

### Installing Component Updates

This section covers common <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> files like `admin`, `curriculum`, `control`, and `type`.

<Steps>
1. **Check Update is Available**

   Check if the <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> you want to install is on your computer and see which version it is.

   ```bash
   # Check for the latest 'admin' component
   tl-comp-latest admin

   # Check for the latest 'docs' curriculum
   tl-comp-latest curriculum docs
   ```

2. **Run the Installer**

   There are 2 different commands for installing components.

   **For Most Components:**

   Use the `tl-archive-install` command for most components like `admin`, `type`, `control`, etc.

   ```bash
   # Install the latest available version of 'admin'
   tl-archive-install admin
   ```

   **For the Curriculum:**

   The `curriculum` has its own special installer.

   ```bash
   # Install the latest curriculum (installs the newest version if you don't specify one)

   tl-curriculum-install <subject> <version>

   # Example: Install the latest version of the 'docs' curriculum
   tl-curriculum-install docs
   ```

3. **Check the Installation**

   After the installation finishes, check the new version number.

   ```bash
   # For most components (e.g., admin)
   cat /opt/admin/.version
   ```

</Steps>

---

### Installing a Desktop Patch

This section covers applying a minor **patch update** for the Desktop (e.g., from `26.6.0` to `26.6.1`) from files that are already on the computer.

> [!IMPORTANT] **For major version updates**
> When moving from one major version to the next, use one of the
> [USB Update methods](/docs/updating/#standard-desktop-computers).

<Steps>
1. **Check Available Version**

   Check the version of the `desktop` <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr> that is available locally.

   ```bash
   tl-comp-latest desktop
   ```

2. **Unpack the Update Image**

   Unpack the Desktop image, replacing `x.x.x` with the version number you found above.

   ```bash
   tl-img-unpack /var/btrfs x.x.x
   ```

3. **Apply the Update**

   Restore the unpacked image to apply the update.

   ```bash
   tl-img-restore /var/btrfs x.x.x
   ```

4. **Finalize**

   Reboot the computer to complete the installation.

   ```bash
   sudo reboot
   ```

</Steps>

---


### Advanced Tools & Networking


This section contains guides for more complex or less frequent tasks that require careful attention to detail.

<CardGrid>
  <LinkCard title="Router Configuration" href="/docs/advanced/router/" description="A step-by-step guide for configuring a TP-Link router to work with the TechLit classroom network." />
  <LinkCard title="Downloading YouTube Videos" href="/docs/advanced/youtube/" description="How to install and use the command-line tool yt-dlp to download educational videos for offline use." />
  <LinkCard title="Create an Installer USB" href="#create-or-re-provision-an-installer-usb" description="How to prepare a new USB drive or re-provision an existing one to be a bootable TechLit OS installer." />
</CardGrid>

---

## Create or Re-provision an Installer USB

This guide explains how to use the `tl-usb-prepare` command to create a bootable TechLit OS installer from a standard USB drive. This is useful for creating new installer drives or fixing one that is no longer working correctly.

> [!CAUTION]
> This process will permanently erase all data on the USB drive.

<Steps>
1. **Ensure Recovery Image is Present**

   The installer is created from a `recovery` <abbr title="A Component is a pre-configured Software Module. Instead of installing hundreds of individual files, we bundle everything into a single package (a 'component') to make lab management faster.">component</abbr>. First, ensure you have the latest version on your machine.

   ```bash
   tl-comp-latest recovery
   ```

   If it's not present, [download it from the bastion](/docs/updating/get-updates/) first.

2. **Identify the USB Drive**

   Plug the USB drive into your computer and run the following command to identify its device name.

   ```bash
   lsblk
   ```

   Look for a drive that matches the size of your USB. It will likely be named `/dev/sda`, `/dev/sdb`, etc.

3. **Run the Prepare Command**

   Execute the `tl-usb-prepare` command, replacing `/dev/sdX` with the device name you found in the previous step.

   ```bash
   # Example for a USB drive at /dev/sdb
   tl-usb-prepare /dev/sdb
   ```

   The script will handle all partitioning, formatting, and copying of necessary files.

4. **Unplug the Drive**

   Once the script is complete, you can safely unplug the USB drive. It is now ready to be used to [provision other devices](/docs/device_provision/).

</Steps>

### Downloading YouTube Videos

> URL: https://help.techlitafrica.org/docs/advanced/youtube/

This guide explains how to download educational videos from YouTube for offline
use in the classroom. There are 2 methods available: using a recommended
command-line tool or a simple browser add-on.

---

## Before You Begin

Downloading videos can significantly impact your school's network and computer
storage. Follow these guidelines:

- **Copyright Guidance:** Only download videos that are explicitly permitted for
  educational use or fall under "Fair Use" policies. Avoid downloading
  commercial movies or copyrighted music without permission.
- **Storage Caution:** High-quality videos (1080p and above) use a lot of disk
  space. Regularly delete old videos from your public folders to ensure there is
  enough room for new content.

---

## Method 1: Using the Command Line (Recommended)

This method is recommended for its power and reliability. It uses a
command-line tool called `yt-dlp`.

> [!WARNING] **Firewall Must Be Temporarily Disabled**
> To download from YouTube using this method, you must first stop the firewall.
> As the `admin` user, run `rsv stop nftables`. This is the only step that
> requires admin privileges. The rest of the process should be run as the
> `guest` user.

<Steps>
1. **Install `yt-dlp`**

   First, you need to add the `asdf` plugin for `yt-dlp` and install it. This only
   needs to be done once.

   ```bash
   # Add the plugin
   asdf plugin add yt-dlp

   # Install the latest version
   asdf install yt-dlp latest

   # Set it as the global default
   asdf set yt-dlp latest

   # Export the asdf shims to your PATH for the current session
   ```

2. **Navigate to Download Directory**

   Change to the directory where you want to save the videos. By default,
   downloads are saved to the current folder you are in.

   ```bash
   # Save to a teacher's public folder so others can access them
   cd /srv/public/teachers/jdoe
   ```

3. **Download the Video(s)**

   You can now download a video using its URL. The `-f best` flag tells the tool
   to download the best available **merged** video and audio quality.

   **Single Video:**

   ```bash
   yt-dlp -f best https://www.youtube.com/watch?v=Qg1ml3aHAM4
   ```

   **Batch Download (Multiple URLs):**
   You can download multiple videos at once by listing the URLs separated by
   spaces, or by pointing to a text file containing one URL per line.

   ```bash
   # Using multiple URLs
   yt-dlp -f best URL1 URL2 URL3

   # Using a text file (e.g., videos.txt)
   yt-dlp -f best -a videos.txt
   ```

   > [!TIP]
   > For the absolute highest quality (which might download video and audio
   > separately), use `-f bestvideo+bestaudio`. You can also list all available
   > formats with the `-F` flag (e.g., `yt-dlp -F <URL>`).

4. **Restart the Firewall**

   **Important:** Once you have finished downloading your videos, you MUST
   restart the firewall to ensure the computer remains protected.

   ```bash
   # As the admin user
   rsv start nftables
   ```

</Steps>

---

## Method 2: Using a Firefox Add-on (Alternative)

This is an alternative method for users who prefer a graphical interface. It
involves temporarily adding a video downloader tool to the Firefox web browser.

> [!WARNING]
> The add-ons listed in the Firefox store are developed by third parties.
> TechLit does not own, endorse, or provide support for any specific add-on.
> Use them at your own discretion.

<details>
<summary>Firefox add-on steps</summary>


> [!NOTE]
> Add-ons installed in the guest session are temporary. They will be
> automatically removed when you log out or reboot the computer. You will
> need to repeat these steps for each new session.

<Steps>
1. **Open Firefox Add-ons**

   - Open the Firefox browser.
   - Click the menu button (☰) in the top-right corner and select **Add-ons and
     themes**.
   - Alternatively, you can press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> +
     <kbd>A</kbd>.

2. **Find a Downloader Add-on**

   - In the "Find more add-ons" search box, type `youtube downloader` and press
     Enter.
   - Browse the search results and choose an add-on that looks suitable. Read the
     descriptions and reviews to help you decide.

3. **Add the Add-on to Firefox**

   - Once you've chosen an add-on, click on it, and then click the **Add to
     Firefox** button.
   - A permission pop-up will appear. Click **Add** to confirm.

4. **Download the Video**

   - Navigate to the YouTube video you want to download.
   - The add-on will typically add a "Download" button near the video player.
     Click it and follow the on-screen instructions to save the video file to the
     computer.

</Steps>
</details>

---

## Troubleshooting

If your download fails, check the following:

- **Firewall:** Did you run `rsv stop nftables` as the `admin` user? `yt-dlp`
  cannot connect to YouTube if the firewall is active.
- **Disk Space:** Check if the computer has enough space. You can run
  `df -h /srv/public` to see available space in the public folder.
- **Private/Deleted Videos:** Ensure the video is public and hasn't been
  removed by YouTube.
- **Update the Tool:** YouTube often changes how they deliver videos. If
  downloads consistently fail, you may need to update `yt-dlp` by running
  `asdf install yt-dlp latest` again.

---

### Router Configuration

> URL: https://help.techlitafrica.org/docs/advanced/router/

This guide provides detailed, step-by-step instructions for configuring a standard TP-Link router to function as an access point for the TechLit classroom network.

<details>
<summary>**Pre-requisites**</summary>


- Your router has been __reset__ to its original factory settings.
- You may use any __client__ to configure the router.
- Configuring __multiple routers__? see the [table](#multiple-routers-scenario) below

</details>

<details>
<summary>**Router options**</summary>


- __Admin password__ = `empowerwatoto1`
- __SSID__ = TechLit Africa/Vim/Emacs
- __Operation Mode__ = AP
- __Network__ = Static IP
- __Subnet__ = 192.168.1.0
- __Mask__ = 255.255.255.0
- __DHCP__ = disabled
- __Width__ = 40 MHz
- __Channel__ = See the table below [table](#multiple-routers-scenario)
- __IP__ = See [table](#multiple-routers-scenario)
- __Password__ = `empowerwatoto`
- __TX Power__ = Low

</details>

## How to configure the router

<Steps>
1. **Disconnect the router**

   Disconnect all Ethernet connections from the router, and
   disconnect the server if it is connected over Wi-Fi.

2. **Connect a client to the router**

   - Look for an SSID named `TP-Link_xxx` in your Wi-Fi network list.
   - The default password is usually found on a label beneath the router.

3. **Open interface**

   Open the router's web interface in a web browser __here__:
   [192.168.0.1](http://192.168.0.1)

   - Enter `192.168.0.1` in your web browser to access the router's settings.
   - You'll be prompted to set a new admin password for security purposes.
   - The router's interface should now be visible to you.

   ![Web interface](web_interface.png "tp-link Web Interface")

4. **Configure Operation Mode**

   To change __Operation Mode__ - Select `Operation Mode` from the side menu. - Choose `Access Point` mode, save the changes,
   and wait for the router to reboot.
   ![Operation mode](ap_mode.png "Router Operation mode")

5. **Configure SSID, Width and Channel**

   To change the __SSID__, __Width__ and __Channel__

   - Navigate to `Wireless` settings in the side menu.
   - Set the `Wireless Network Name` to your desired SSID.
   - Adjust `Channel Width` to __40 MHz__ for better performance.
   - Set the `Channel` to Auto or if using multiple routers,
     as per the provided [table](#multiple-routers-scenario).
   - Save the changes and reconnect using the new SSID with the previous password.

   ![Wireless Settings](wireless.png "Router wireless settings")

6. **Set Password**

   - Go to `Wireless Security` settings under the `Wireless` menu.
   - Choose `WPA/WPA2 - Personal` and enter the Wi-Fi password.
   - Save and reconnect to the SSID using the new password.

   ![Wireless](wireless_security.png "Router wireless settings")

7. **Configure IP and Gateway**

   - Select `Network` from the main menu and choose `LAN` settings.
   - Opt for `Static IP` and input the correct IP address.
   - Set the `Gateway` to 192.168.1.1
   - Save the settings and let the router reboot.

   ![Network](network_ip.png "Router wireless settings")

8. **Disable DHCP**

   - After setting the new IP, access the web interface using the new address
     (e.g., `192.168.1.100`).
   - Log in with the new IP and admin password.
   - Go to `DHCP` settings and click on `Disable`.

   ![DHCP](dhcp.png "Router DHCP settings")

</Steps>

:::caution
Once DHCP is disabled, you must connect the router to the server computer to provide network
access. See the [Network & Wi-Fi](/docs/network/) for more details.
:::

<br />

---

### Multiple Routers scenario

This table gives the standard configuration for 6 access points.
Below are the settings for each AP:

| SSID                | IPv4 Address  | Channel |
| ------------------- | ------------- | ------- |
| TechLit Vim         | 192.168.1.100 | 2       |
| TechLit Emacs       | 192.168.1.102 | 10      |
| TechLit Vim Yank    | 192.168.1.100 | 2       |
| TechLit Vim Paste   | 192.168.1.101 | 10      |
| TechLit eMacs Mark  | 192.168.1.102 | 2       |
| TechLit eMacs Point | 192.168.1.103 | 10      |

---


## Changelog


Here you can find a list of recent changes and improvements to the TechLit System documentation.

- [Curriculum Component Split](/changes/2026-04-29-curriculum-split/)
- [Refactored 'Updating' Documentation](/changes/2026-01-14-updating-docs-refactor/)

### Curriculum Component Split

> URL: https://help.techlitafrica.org/changes/2026-04-29-curriculum-split/
> Published: 2026-04-29

The curriculum component has been split into multiple subjects. This allows for faster updates and more granular control over what subjects are installed on each computer.

## What Changed?

- **Subject-Specific Packages:** Instead of one large `curriculum` component, we now have subject-specific packages (e.g., `docs`, `sheets`, `shell`).
- **New Installer Syntax:** The `tl-curriculum-install` command now requires a subject name.

## How to Install

To install or update a specific curriculum subject, use the following command:

```bash
tl-curriculum-install <subject>
```

For more details, see the updated [Installing Local Updates](/docs/updating/get-updates/#installing-local-updates) guide.

---

### Refactored 'Updating' Documentation

> URL: https://help.techlitafrica.org/changes/2026-01-14-updating-docs-refactor/
> Published: 2026-01-14

We've completely overhauled the "Updating" section of the documentation to
make it clearer, more concise, and easier to follow.

## Key Improvements

- **Task-Oriented Guides:** The old, monolithic guides have been broken down
into focused, step-by-step instructions for specific tasks
(e.g., updating standard desktops, small devices, Chromebooks).
- **Clearer Navigation:** The main "Updating" page now serves as a simple
portal to guide you to the exact procedure you need.
- **Consolidated Install Steps:** The process for installing component updates
and desktop patches (from LAN) has been merged into a single, logical guide.

We believe these changes will make the update process much less confusing.
As always, we welcome your feedback.

---


## Stats

The stats pages are generated reports. This file does not repeat the
per-row data. Read the live report at:
https://help.techlitafrica.org/stats/

CSV exports under /stats/:
- https://help.techlitafrica.org/stats/history/01-05-2026.csv
- https://help.techlitafrica.org/stats/history/02-10-2026.csv
- https://help.techlitafrica.org/stats/history/03-07-2026.csv
- https://help.techlitafrica.org/stats/history/04-09-2026.csv
- https://help.techlitafrica.org/stats/history/05-06-2026.csv
- https://help.techlitafrica.org/stats/history/08-05-2026.csv
- https://help.techlitafrica.org/stats/history/09-10-2026.csv
- https://help.techlitafrica.org/stats/history/10-07-2026.csv
- https://help.techlitafrica.org/stats/history/11-09-2026.csv
- https://help.techlitafrica.org/stats/history/12-06-2026.csv
- https://help.techlitafrica.org/stats/history/15-05-2026.csv
- https://help.techlitafrica.org/stats/history/16-10-2026.csv
- https://help.techlitafrica.org/stats/history/17-07-2026.csv
- https://help.techlitafrica.org/stats/history/18-09-2026.csv
- https://help.techlitafrica.org/stats/history/19-06-2026.csv
- https://help.techlitafrica.org/stats/history/22-05-2026.csv
- https://help.techlitafrica.org/stats/history/24-07-2026.csv
- https://help.techlitafrica.org/stats/history/25-09-2026.csv
- https://help.techlitafrica.org/stats/history/26-06-2026.csv
- https://help.techlitafrica.org/stats/history/28-08-2026.csv
- https://help.techlitafrica.org/stats/history/29-05-2026.csv
- https://help.techlitafrica.org/stats/history/31-07-2026.csv
- https://help.techlitafrica.org/stats/history_models.csv
- https://help.techlitafrica.org/stats/latest.csv
- https://help.techlitafrica.org/stats/latest_models.csv
- https://help.techlitafrica.org/stats/school_hardware_map.csv
- https://help.techlitafrica.org/stats/summaries/schools/amagoro.csv
- https://help.techlitafrica.org/stats/summaries/schools/bahakwenu.csv
- https://help.techlitafrica.org/stats/summaries/schools/calvary.csv
- https://help.techlitafrica.org/stats/summaries/schools/chepyuan.csv
- https://help.techlitafrica.org/stats/summaries/schools/egu.csv
- https://help.techlitafrica.org/stats/summaries/schools/fuyele.csv
- https://help.techlitafrica.org/stats/summaries/schools/kapkures.csv
- https://help.techlitafrica.org/stats/summaries/schools/kipkenyo.csv
- https://help.techlitafrica.org/stats/summaries/schools/lekuruki.csv
- https://help.techlitafrica.org/stats/summaries/schools/little-lambs.csv
- https://help.techlitafrica.org/stats/summaries/schools/magale.csv
- https://help.techlitafrica.org/stats/summaries/schools/mgalani.csv
- https://help.techlitafrica.org/stats/summaries/schools/mirera-emacs.csv
- https://help.techlitafrica.org/stats/summaries/schools/mirera-vim.csv
- https://help.techlitafrica.org/stats/summaries/schools/murengeti.csv
- https://help.techlitafrica.org/stats/summaries/schools/muruai.csv
- https://help.techlitafrica.org/stats/summaries/schools/ndatho.csv
- https://help.techlitafrica.org/stats/summaries/schools/pendo.csv
- https://help.techlitafrica.org/stats/summaries/schools/raya.csv
- https://help.techlitafrica.org/stats/summaries/schools/salama.csv
- https://help.techlitafrica.org/stats/summaries/schools/sns-emacs.csv
- https://help.techlitafrica.org/stats/summaries/schools/sns-vim.csv
- https://help.techlitafrica.org/stats/summaries/schools/taru.csv
- https://help.techlitafrica.org/stats/summaries/schools/zawadi.csv
- https://help.techlitafrica.org/stats/summaries/teachers/ann-atong.csv
- https://help.techlitafrica.org/stats/summaries/teachers/diana.csv
- https://help.techlitafrica.org/stats/summaries/teachers/dominic.csv
- https://help.techlitafrica.org/stats/summaries/teachers/essy.csv
- https://help.techlitafrica.org/stats/summaries/teachers/evah.csv
- https://help.techlitafrica.org/stats/summaries/teachers/evans.csv
- https://help.techlitafrica.org/stats/summaries/teachers/jane-mary.csv
- https://help.techlitafrica.org/stats/summaries/teachers/jebungei.csv
- https://help.techlitafrica.org/stats/summaries/teachers/joylene.csv
- https://help.techlitafrica.org/stats/summaries/teachers/katheu.csv
- https://help.techlitafrica.org/stats/summaries/teachers/kennedy.csv
- https://help.techlitafrica.org/stats/summaries/teachers/manasseh.csv
- https://help.techlitafrica.org/stats/summaries/teachers/marega.csv
- https://help.techlitafrica.org/stats/summaries/teachers/maurice.csv
- https://help.techlitafrica.org/stats/summaries/teachers/maurine.csv
- https://help.techlitafrica.org/stats/summaries/teachers/mercy.csv
- https://help.techlitafrica.org/stats/summaries/teachers/miringu.csv
- https://help.techlitafrica.org/stats/summaries/teachers/pauline.csv
- https://help.techlitafrica.org/stats/summaries/teachers/pepit.csv
- https://help.techlitafrica.org/stats/summaries/teachers/quinn.csv
- https://help.techlitafrica.org/stats/summaries/teachers/rebecca.csv
- https://help.techlitafrica.org/stats/summaries/teachers/shakeem.csv
- https://help.techlitafrica.org/stats/summaries/teachers/tobias.csv
- https://help.techlitafrica.org/stats/summaries/teachers/waceke.csv

## Blogs


Posts and guides from the TechLit team.

## [Git & GitLab Onboarding: Working Safely on TechLit Computers](/blog/git-onboarding-guide/)

A complete guide to configuring your Git environment, managing persistent SSH keys, and mastering the feature-branch workflow.

2026-05-21

### Git & GitLab Onboarding: Working Safely on TechLit Computers

> URL: https://help.techlitafrica.org/blog/git-onboarding-guide/
> Published: 2026-05-21

Welcome to the TechLit Africa contributor team! This guide will walk you through setting up your terminal environment on our workstations. Because our default user home is reset on logout, we must use specific persistent paths to ensure your security keys and code projects are never lost.

:::danger
**CRITICAL: PERSISTENT vs. EPHEMERAL STORAGE**
On all standard **TechLit computers**, the default home directory (`~` or `/home/guest`) is wiped completely every time you log out or the system resets. To prevent losing your work, you **must** use the persistent storage area at `/srv/public/`.
:::

:::note
**Note on Usernames:** In the examples below, we use the name `denis`. **This is a placeholder.** Please replace `denis` with your actual TechLit username (e.g., `/srv/public/teachers/amina/guest/`) whenever you type a command.
:::

---

## Phase 1: Environment & Key Provisioning

> **Objective:** Setup your GitLab account, generate persistent security keys, and configure your global Git identity.
> **Estimated time:** 10 minutes

### 1.1 GitLab Account Setup

Before you start working in the terminal, you need a GitLab account to identify your contributions.

1. **Register:** Go to [GitLab.com](https://gitlab.com) and create a free account.
2. **Join the Group:** Once your account is ready, request **GitLab write access** on WhatsApp. Provide your GitLab username, and you will be added to the [techlit-africa](https://gitlab.com/techlit-africa) workspace.

### 1.2 Persistent SSH Configuration

To connect to GitLab without a password, we generate an SSH key. We store this in your persistent folder so it survives a logout.

**Action Commands:**

```bash
# 1. Create the secure folder (Use your actual username instead of 'denis')
mkdir -p /srv/public/teachers/denis/guest/.ssh

# 2. Cd into your persistent guest directory
cd /srv/public/teachers/denis/guest

# 3. Generate the key
ssh-keygen -t ed25519 -f .ssh/id_ed25519 -C "denis@techlitafrica.org"

# 4. Link for GitLab Access (Removes need for -i flag)
ln -s /srv/public/teachers/denis/guest/.ssh/id_ed25519 /srv/guest/gitlab_ssh
```

**Verification Step:**

**Visual Checkpoint:**
<Asciinema file="casts/ssh-setup.cast" autoplay="false" />

### 1.3 Git Identity Setup

Git needs to know who is making changes so that your name appears correctly in the project history.

**Action Commands:**

```bash
# Set your name and email
git config --global user.name "Denis"
git config --global user.email "denis@techlitafrica.org"
```

:::caution
**Note:** Global Git configuration is stored in `~/.gitconfig`, which is wiped on logout. To make your identity persistent, you can symlink it to your persistent folder:
`ln -s /srv/public/teachers/denis/guest/.gitconfig ~/.gitconfig`
:::

**Verification Step:**

```bash
git config --list
```

---

## Phase 2: Local Workspace & The 3-Stage Pipeline

> **Objective:** Create safety backups, clone the project, and master the local saving cycle.
> **Estimated time:** 15 minutes

### 2.1 Safe Folder Backups: Your Manual Undo Button

Before practicing Git commands, always make a local duplicate of your folder. This is your 100% safe "undo button" if a command gets confusing.

**Action Commands:**

```bash
# 1. Navigate to your projects directory
cd /srv/public/teachers/denis/guest/projects

# 2. Duplicate your project folder before experimenting
cp -r websites websites_backup
```

### 2.2 The "Git Status" Mantra

Think of `git status` as the terminal user's eyes. Run it before you add a file, after you stage it, and right before you commit. If you ever feel lost, `git status` is the first command you should type.

### 2.3 Project Cloning

Pull the `websites` repository from GitLab into your persistent projects folder.

**Action Commands:**

```bash
git clone git@gitlab.com:techlit-africa/websites.git
cd websites
ls
```

**Visual Checkpoint:**
<Asciinema file="casts/clone.cast" autoplay="false" />

### 2.4 Saving Your Work: The Three Stages

Git uses a holding zone to help you organize what you save.

1. **Modified:** You have edited a file (e.g., `src/main.js`) but haven't told Git to save it yet.
2. **Staged (`git add`):** You have picked which changes you want to include in your next save. Think of this as putting files into a "to-be-saved" box.
3. **Committed (`git commit`):** You have permanently saved the snapshot of your staged files to your local history.

**Branching & Staging:**

```mermaid
%%{init: { 'theme': 'default', 'themeVariables': { 'fontSize': '28px' }}}%%
graph LR
    subgraph Remote["GitLab (Remote Server)"]
        RM[main branch]
        RFB[remote branch]
        MR{Merge Request}
    end

    subgraph Local["Your dev computer (Persistent)"]

        LM[main branch]
        FB[feature-branch]
        
        Edit[Edit Files] --> Modified(Modified)
        Modified -- "git add" --> Staged(Staged)
        Staged -- "git commit" --> Committed(Committed)
    end

    RM -- "git clone" --> LM
    LM -- "git switch -c feature-branch" --> FB
    FB --> Edit
    Committed -- "git push" --> RFB
    RFB -- "Open MR" --> MR
    MR -- "Merged" --> RM
```


---

## Phase 3: Team Sync & Upstream Collaboration

> **Objective:** Master feature branching, keep your work current, and share changes via Merge Requests.
> **Estimated time:** 15 minutes

### 3.1 Feature Branching Workflow

We never edit the `main` branch directly. We use **Feature Branches** to keep our production code stable.

**Action Commands:**

```bash
# 1. Start with the latest code
git switch main
git fetch origin
git pull origin main

# 2. Create your experimental branch
git switch -c feature/add_new_feature
```

**Visual Checkpoint:**
<Asciinema file="casts/sync.cast" autoplay="false" />

### 3.2 Keeping Your Branch Current

If you haven't worked on your feature branch for a few days, rebase it to include the latest team changes.

**Action Commands:**

```bash
git switch main
git pull origin main
git switch feature/add_new_feature
git rebase main
```

**Visual Checkpoint:**
<Asciinema file="casts/branch-commit.cast" autoplay="false" />

### 3.3 Pushing Changes & Opening an MR

Once you have committed your work locally, send it to GitLab to share it with the team.

**Action Command:**

```bash
git push origin feature/add_new_feature
```

**Visual Checkpoint:**
<Asciinema file="casts/push-mr.cast" autoplay="false" />

### 3.4 Troubleshooting & Escape Hatches

* **The Escape Hatch:** If a rebase or merge becomes confusing, go back to safety with `git rebase --abort`.
* **Clean Workspaces:** Always check your `.gitignore` to ensure temporary files aren't being tracked.
* **The snapshot rule:** Anything left in `~/` or `/home/guest` **disappears forever** on logout. Always verify your path with `pwd`.

**Congratulations!** You are now ready to contribute safely and effectively to the TechLit Africa project.

---


---

Generated on 2026-10-16 14:41:33 UTC
Site: https://help.techlitafrica.org/
