Internet-in-a-Box (IIAB) Platforms

Operating Systems

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

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.
    - HEADLESS OPTION: If you choose Raspberry Pi OS “Lite” (instead of “with desktop”) and want to install IIAB using a WiFi connection to the Internet (instead of using an Ethernet cable to the Internet) here are instructions to set up Wi-Fi up via the command-line — which expands on the basic headless instructions.
    - HISTORICAL: Consider the 64-bit forum discussion and IIAB install tips at #2422.
  - 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
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)
- Ubuntu 24.10 “Oracular Oriole” was released 2024-10-10 (release notes, installation):
  - More experimentally, IIAB can also be installed on Ubuntu 24.10 on Raspberry Pi, especially if your Raspberry Pi has 4+ GB RAM (tutorial, install guide).
  - KA Lite is not feasible, as a Python 2 virtualenv appears no longer practical. Please consider Kolibri instead: #3733 #3776
  - Transmission 4.x does not currently work, regardless whether compiled (set transmission_compile_latest: True in /etc/iiab/local_vars.yml) or installed via apt: #3756
- Debian 13 (Trixie) should work even prior to its final release expected mid-2025 (pre-release download options, release notes, micronews). CAUTION: Debian Edu (Skolelinux, #2831) is not supported at this time. #3736
  - Add the line VERSION_ID="13" to /etc/os-release before installing IIAB!
  - KA Lite is not feasible, as a Python 2 virtualenv appears no longer practical. Please consider Kolibri instead: #3733 #3776
- Ubuntu 25.04 “Plucky Puffin” final release is expected 2025-04-17 (release notes, bugs) and its pre-releases already work well with IIAB, on PCs and VMs especially:
  - Pre-release “daily” builds are quickly installable as Multipass VM’s — or download an ISO-or-similar to install onto a regular PC (server live, server preinstalled, desktop live, desktop preinstalled).
  - More experimentally, IIAB can also be installed on Ubuntu 25.04 on Raspberry Pi pre-releases, especially if your Raspberry Pi has 4+ GB RAM (tutorial, install guide).
  - KA Lite is not feasible, as a Python 2 virtualenv appears no longer practical. Please consider Kolibri instead: #3733 #3776
  - Transmission 4.x does not currently work, regardless whether compiled (set transmission_compile_latest: True in /etc/iiab/local_vars.yml) or installed via apt: #3756
- “Pure Debian” for Raspberry Pi: https://raspi.debian.net (At Your Own Risk!)
- Debian “Sid” for developers (At Your Own Risk!)
The following OS’s are NO LONGER RECOMMENDED at this time: (modify /opt/iiab/iiab/scripts/local_facts.fact Lines 85-100 if necessary)
- Linux Mint 21.3+ works very well (OS is built on Ubuntu 22.04) if your community needs a graphical desktop on the very same machine as Internet-in-a-Box: PR #2483, PR #2501, PR iiab/iiab-admin-console#336.
- Ubuntu 22.04 LTS “Noble Numbat” released 2024-04-25 (release notes) works well on PC, or more experimentally on Raspberry Pi (tutorial, install guide).
- Ubuntu 23.10 “Mantic Minotaur” (release notes) was released 2023-10-12 and works well with IIAB on PCs and VMs especially, if you avoid Lokole (#3528).
  - More experimentally, IIAB can also be installed on Ubuntu 23.10 on Raspberry Pi, especially if your Raspberry Pi has 4+ GB RAM (tutorial, install guide, wiki).
  - 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
- Raspberry Pi OS “Bullseye” (based on Debian 11) e.g. 64-bit with desktop or 32-bit Lite if absolutely necessary.
- Raspberry Pi Desktop for PC a.k.a. Debian Bullseye with Raspberry Pi Desktop (for PC, x86_64 VM, or Mac) will NOT work with modern Node.js apps — as a result of this distro’s hybrid 32-bit and 64-bit CPU arch legacy (specifically, i386-instead-of-amd64 versions of python3 packages) which lead to serious Node.js 10.x problems across the board. Sugarizer can be made to work if absolutely necessary. But this is ENTIRELY AT YOUR OWN RISK. Extensive details written up on 2021-07-21: #2873
  - Manually install Node.js and npm, running these 2 lines as root: (for roles/internetarchive, roles/jupyterhub, roles/nodered, roles/pbx i.e. Asterisk/FreePBX and/or roles/sugarizer)
    - sudo apt install nodejs npm # Installs Node.js 10.x.y (for now — 12.x.y, 14.x.y, 16.x.y, 18.x.y or 20.x.y later?) and npm 7.x.y (for now)
    - sudo echo ‘nodejs_installed: True’ >> /etc/iiab/iiab_state.yml
- Debian 11 (Bullseye), as was released 2021-08-14 (download, release notes). Install tips are at PR #2582 (since Oct 2020) and #2749 (since Apr 2021).
  - CAUTION: Support for this OS’s PHP 7.4 ended on 2022-11-03. #3467
  - CAUTION: Debian Edu (Skolelinux, #2831) is not supported at this time.
- Ubuntu 23.04 (Lunar Lobster) (release notes) was released 2023-04-20 for PC (amd64), and more experimentally for Raspberry Pi (tutorial, install guide, wiki).
  - INSTALL TIPS, very similar to Debian 12: #3399
- Ubuntu 22.10 (Kinetic Kudu) (release notes) was released 2022-10-20 for PC (amd64), and more experimentally for Raspberry Pi (tutorial, install guide, wiki).
  - 2022-10-24 INSTALL TIPS: #3343 #3408
- Ubuntu 20.04.5+ LTS (Focal Fossa) on PC (amd64), or more experimentally on Raspberry Pi (tutorial, install guide, wiki).
  - REQUIRED: Manually revert plocate to mlocate in /opt/iiab/iiab/roles/2-common/tasks/packages.yml #3365 #3377
- Linux Mint 20
  - REQUIRED: Manually revert plocate to mlocate in /opt/iiab/iiab/roles/2-common/tasks/packages.yml #3365 #3377
- Ubuntu 21.10 (Impish Indri) was released 2021-10-14 (download). Ubuntu End-of-Life for this non-LTS OS is July 2022. Install tips: #2818
- Raspberry Pi OS “Buster” was released 2019-06-25.
- Ubuntu 21.04 (Hirsute Hippo) also includes Raspberry Pi installers. Ubuntu End-of-Life for this non-LTS OS is January 2022. Install tips may be found at PR #2635 and #2744.
- Debian 10 “Buster” LTS on AMD64 (installer, #1387 install tips)
- Raspberry Pi OS (Legacy), based on Debian 10 “Buster”.
- Ubuntu 20.10 (Groovy Gorilla) (64-bit, Server or Desktop) for Raspberry Pi:
  - Ubuntu End-of-Life for this non-LTS OS was July 2021.
  - Known Issue: Ubuntu Desktop 20.10 will fail to allow client devices to connect to (e.g. Raspberry Pi’s) internal hotspot. As of 2020-11-13, a temporary workaround is to edit /etc/default/networkd-dispatcher to read just networkd_dispatcher_args="" and run sudo ip link set ap0 up #2585
  - 64-bit Ubuntu MATE 20.10 (graphical desktop) appears to work surprisingly well: #2585 (comment)
  - See possible residual issue(s) with Bluetooth, MongoDB and NetworkManager: #2585
- Ubuntu 18.04 LTS on AMD64. WARNINGS: (A) IIAB’s 1-line installer must be run as root! (B) Packages like MediaWiki 1.35 LTS will fail, as Ubuntu 18.04’s PHP 7.2 is too old.
- Ubermix 4.x based on Ubuntu 18.04
  - Create a USB stick (USB drive >= 4GB will suffice initially) to install Ubermix 4.x. Download the latest from http://ubermix.org/files.html and follow the instructions at http://ubermix.org/download.html
  - Read the “Customization Overview” section here: http://ubermix.org/customization.html. This is important information to understand.
  - Use your Ubermix USB install stick to do an ADVANCED install of Ubermix 4.x on your designated computer (turn off UEFI in its BIOS if possible) following the instructions under “Installing on your System” here: http://ubermix.org/download.html
    - You need to shrink the /home partition to make room for content to be stored in /library. Change partition sizes by selecting Option 2 (“Advanced image”) to set a larger size for the Default System partition (/dev/ext2) and/or larger size for the User Changes partition (/dev/ext3). You will be prompted to manually enter in partition sizes.
      - e.g. for an 80GB hard drive, consider 12GB (default) for the Default System partition and 50GB for the User Changes partition (IF /library IIAB content will be stored in the User Changes partition, wiped during factory reset reverts). You can adjust the partition sizes as necessary based on your hard drive size and content size needs.
      - e.g. consider reversing this: 50GB for the Default System partition and 12GB for the User Changes partition (IF /library IIAB content will be stored in the Default System partition, to protect it from factory reset reverts)
    - Ubermix will install in ~5 or so minutes.
  - Once Ubermix is installed and you are logged in, confirm the partitions are as you expect by opening up the Terminal and entering “df -h”. Proceed if all is as expected.
  - Turn off aufs (UnionFS). Follow steps #2-6 under the “Rebuilding the Base Image” section here: http://ubermix.org/customization.html
  - Congratulations, you are now ready to install IIAB.
  - Install curl, by manually running: sudo apt install curl
  - Run IIAB’s 1-line installer: https://download.iiab.io
  - Turn aufs (UnionFS) back on.
  - Consider building a USB stick to install everything at once onto other laptops/desktops, reading “Rebuilding the Base Image” in http://www.ubermix.org/customization.html (“5. Expert Options”, then “1. Update the image on the key using this machine as a model”)
- Ubuntu Server 19.10.1 for Raspberry Pi released 2019-12-05 (docs, downloads). Stick with the 32-bit version for now, until 64-bit Kiwix support appears (kiwix/kiwix-build#396). Please do not install or enable Sugarizer in /etc/iiab/local_vars.yml as this OS lacks MongoDB.
- Ubuntu 19.10 Eoan Ermine:
  - Server & Desktop editions for AMD64, released 2019-10-17
    - Install Tips: #2003
- Debian 9.x “Stretch” LTS
- CentOS 7.x LTS
- Ubuntu 16.04 LTS
- Debian 8.x “Jessie” LTS
- Fedora 18 (32-bit) for legacy support of One Laptop per Child’s (OLPC) XO laptops

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