Skip to content

IIAB Platforms

Jump to bottom
A Holt edited this page Oct 24, 2024 · 613 revisions

Internet-in-a-Box (IIAB) Platforms

Operating Systems

Read the partition scheme below.

Install a minimal OS, as the Internet-in-a-Box (IIAB) installer will add the packages you need.

  1. PLEASE CHOOSE ONE OF THESE 4 GNU/LINUX OS's: (summarized at FAQ.IIAB.IO > "What OS should I use?")

    • Raspberry Pi OS
      • Raspberry Pi OS "Bookworm" (64-bit) was released 2023-10-11, based on Debian 12. IIAB testing began 2023-04-04 (#3526) and touch-ups were added 2023-10-14 (PR #3660 to resolve systemd-resolved issue #3657) now that the OS is officially released! (As originally announced February 2022, their 64-bit OS now works on Raspberry Pi Zero 2 W, 3, 3 B+, 4, 5 and 400.) It's available in a Lite (headless) version or with desktop, and has come a long way since its 2020-05-28 beta.
        • ADVANTAGES: "48% faster" than 32-bit. Your IIAB microSD card will also work in newer $15 Zero 2 W computers (if you don't overstress its 512MB RAM!) Also, Calibre e-book software can be installed, making essential commands like calibredb and ebook-convert available to schools building thoughtful e-book collections (whereas it's no longer possible to run sudo apt install calibre on 32-bit Raspberry Pi OS "Bullseye" and higher).
        • DISADVANTAGE: 64-bit IIAB microSD cards won't work in older 32-bit machines like the $10 Raspberry Pi Zero W.
      • Raspberry Pi OS "Bookworm" (32-bit) if you really want the original (slower!) Raspberry Pi OS:
        • ADVANTAGE: Your IIAB microSD card can work in older $10 Zero W computers (if you don't overstress its 512MB RAM!)
        • DISADVANTAGES: JupyterHub and Calibre-Web cannot be installed as of November 2022. Also, Calibre e-book utilities cannot be installed. In addition, Node.js applications like Internet Archive, JupyterHub, Node-RED, PBX (Asterisk/FreePBX) and Sugarizer won't work on Raspberry Pi Zero W (ARMv6) if you installed Node.js while on RPi 3, 3 B+ (ARMv7) or RPi 4 (ARMv8). Read IIAB's Node.js tips if you want to try to make one of the apps work on Zero W.
      • WARNING: The Raspberry Pi's older NOOBS OS IS NOT SUPPORTED.
    • Ubuntu 24.04.1+ LTS (Noble Numbat) originally released 2024-04-25, works well on PC (amd64), or more experimentally on Raspberry Pi (tutorial, install guide). #3662
      • If you absolutely must install IIAB using a Wi-Fi connection to the Internet (instead of an Ethernet cable to the Internet) then before you first boot Ubuntu on Raspberry Pi, you should: (A) Enter your building's Wi-Fi SSID and password using Raspberry Pi Imager's Advanced Options (in the past they recommended editing the pre-existing network-config file, at the top-level of the microSD card). (B) Boot the microSD card in your Raspberry Pi, log in, and run sudo mv /etc/netplan/50-cloud-init.yaml /etc/netplan/02-iiab-config.yaml. (C) Finally, your IIAB should contain just these 2 files in /etc/netplan (ideally!) if you choose to abide by recommended norms — if so create/edit them (with your building's actual SSID and password) to appear as in these 2 examples:

        • /etc/netplan/00-installer-config.yaml or /etc/netplan/01-iiab-config.yaml should contain the "ethernets:" section:

          network:
  ethernets:
    eth0:
      dhcp4: yes
      optional: true

          (You might need to change eth0 above, to the actual Ethernet interface name shown by the ip addr command. ALSO PLEASE READ #3385 CAREFULLY, IF ATTACHING AN EXTERNAL WIFI DEVICE!)

        • /etc/netplan/02-iiab-config.yaml should contain the "wifis:" section — populated with your building's actual WiFi-to-Internet SSID and password:

          network:
  wifis:
    wlan0:
      dhcp4: true
      optional: true
      access-points:
        ACTUAL-SSID:
          password: ACTUAL-PASSWORD

          (You might need to change wlan0 above, to the actual Wi-Fi interface name shown by the ip addr command.)

        • Learn more at: IIAB Networking > Netplan

      • KA Lite is not feasible, as a Python 2 virtualenv appears no longer practical. Please consider Kolibri instead: #3733 #3776
      • Beware Munin might not start until reboot on Raspberry Pi's especially, complicating your IIAB install. Similar to what was first observed on Debian 12 and Ubuntu 23.04: #3434
    • Linux Mint 22+ (download, blog) works very well (OS is built on Ubuntu 24.04 LTS) if your community needs a graphical desktop on the very same machine as Internet-in-a-Box!
      • KA Lite is not feasible, as a Python 2 virtualenv appears no longer practical. Please consider Kolibri instead: #3733 #3776
    • Debian 12 (Bookworm) was released 2023-06-10 and works well (download, other options, release notes, what's new, micronews). CAUTION: Debian Edu (Skolelinux, #2831) is not supported at this time. #3399

  1. The following OS's are THEORETICALLY POSSIBLE, but may require extensive babysitting to get right: (modify /opt/iiab/iiab/scripts/local_facts.fact Lines 85-100 if necessary)

  2. The following OS's are NO LONGER RECOMMENDED at this time: (modify /opt/iiab/iiab/scripts/local_facts.fact Lines 85-100 if necessary)

Contact us if you can help, as user-driven testing & co-design are greatly appreciated, strengthening everyone's community product!

/etc/apt/trusted.gpg Legacy Keyring Warnings

These warnings are harmless, but FYI if you've installed IIAB Apps like Sugarizer or Internet Archive, then commands like apt update will warn you every time: "Key is stored in legacy trusted.gpg keyring (/etc/apt/trusted.gpg), see the DEPRECATION section in apt-key(8) for details."

  • Subsequent runs of sudo iiab are no longer blocked (by apt update warnings about /etc/apt/trusted.gpg) as of November 2022, thanks to PR iiab/iiab-factory#236.
  • Still, if you want to eliminate these apt warnings after installing Sugarizer (and hence MongoDB), run: 
    apt-key list
rm /etc/apt/sources.list.d/mongodb-org.list
apt-key del 90CF B1F5
    It will delete the key and warn you: 
    Warning: apt-key is deprecated. Manage keyring files in trusted.gpg.d instead (see apt-key(8)).
  • Likewise if you installed roles/internetarchive and hence yarn (e.g. as part of a LARGE-sized IIAB install), you can run: 
    rm /etc/apt/sources.list.d/yarn.list
apt-key del 86E5 0310

Hardware Platforms

Theoretically Internet-in-a-Box (IIAB) should run on any machine that can run Ubuntu, Debian or close derivatives (like Raspberry Pi OS, Linux Mint, Ubermix, etc).

In practice, IIAB has been tested on the platforms and configurations below. For more detail, see "What hardware should I use?" within FAQ.IIAB.IO

Raspberry Pi 3, 3 B+, 4 or 400

2GB RAM (or higher) is preferred, but 1 GB RAM (or even 512 MB RAM) can still work on a Raspberry Pi if you carefully build your IIAB without too many apps/services, right-sized for a small community's needs.

Typically a microSD card of 32, 64, 128 or 256 GB will be used, though SSD's have been tested experimentally. Also the Raspberry Pi's 4 USB ports can allow for Ethernet dongles, external Wi-Fi, and possibly additional storage.

(And after building your Internet-in-a-Box microSD in a Raspberry Pi 3, 3 B+, 4 or 400, also consider testing it within the amazing/tiny 512MB Raspberry Pi Zero W, sometimes available for as little as $3.14 at Micro Center stores in the USA. Likewise consider the much faster $15 Raspberry Pi Zero 2 W released on 2021-10-28.)

Intel NUC and Gigabyte BRIX

Mini PC's also include MSI and Zotac etc, typically configured with 4 to 8 GB RAM and a 1TB internal hard disk, or 200+ GB SSD. Most models have a minimum of four USB ports and some have an internal Wi-Fi adapter.

Other Recent Intel/AMD Computers

A number of implementers have successfully deployed IIAB on late model desktop and laptop computers.

VirtualBox VM

Virtual machines (VM's) with varying configurations, especially Ubuntu and Debian, are often used for testing and proofs-of-concept.

OLPC XO-1.5, XO-1.75, XO-4

In the past, IIAB was run on One Laptop Per Child (OLPC) laptops, typically with an SD card of 32, 64, or 128 GB, e.g. with a subset of the content found on machines with more storage, or with an external hard drive.

FYI this used Fedora 18, building on the OLPC OS.

Disk Partitioning

Disable UEFI in your computer's BIOS if possible!

It's critical to avoid a large /home partition, so there's room to add content (in /library). Pay close attention while installing your OS (Ubuntu, Debian etc). You should remove (or dramatically shrink) this /home partition, if your Linux distro insists on creating one.

On a 1+ TB disk, we recommend the following 2-to-4 partitions, such as: (traditionally we use standard partitioning, but now increasingly LVM partitioning is also possible)

  • /boot - 500 MB
  • swap - 2 GB (optional partition, set this to your RAM size, or create a swap file if you prefer)
  • / - 50 GB
  • /library - the remainder (optional partition, can protect your content during major upgrades)

On smaller disks and SD cards, also consider:

  1. reducing (or altogether eliminating) the swap partition — see variable pi_swap_file_size in /etc/iiab/local_vars.yml
  2. avoiding a separate partition for /library — far better to keep your content directory (/library) within the main partition!

Network Adapters

Each of the above devices may have one or more network adapters. These may be internal Ethernet, internal or external Wi-Fi, or Ethernet dongles. The role the server is able to play in the network will depend on what adapters and connections it has.

Sample Gateway Configurations

  • WAN on internal Wi-Fi and LAN on internal Ethernet
  • WAN on internal Ethernet and LAN on internal or external Wi-Fi as Access Point
  • WAN on Ethernet dongle and LAN on internal Ethernet with optional bridged internal/external Wi-Fi as Access Point

Sample Appliance Configurations

  • Internal Wi-Fi connected to an existing LAN
  • Internal Ethernet connected to an existing LAN
  • Ethernet dongle connected to an existing LAN
Clone this wiki locally