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 “Bullseye” (64-bit) works on Raspberry Pi Zero 2 W, 3, 3 B+, 4 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. (WARNING: The NOOBS OS IS NOT SUPPORTED, as its partitioning is very different!)
  - 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”).
  - 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 WiFi up via the command-line — which expands on the basic headless instructions.
  - HISTORICAL: Consider the 64-bit forum discussion and IIAB install tips evolving off #2422.
- Raspberry Pi OS “Bullseye” (32-bit) if you want the original Raspberry Pi OS:
  - ADVANTAGE: Your IIAB microSD card will also work in older $10 Zero W computers (if you don’t overstress its 512MB RAM!)
  - DISADVANTAGES: Calibre e-book utilities cannot be installed. Node.js applications like Asterisk/FreePBX, Node-RED 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). If necessary, run apt remove nodejs or apt purge nodejs then rm /etc/apt/sources.list.d/nodesource.list; apt update then (attempt!) to install Node.js on the Raspberry Pi Zero W itself (a better approach than “cd /opt/iiab/iiab; ./runrole nodejs” is to try apt install nodejs or try installing the tar file mentioned at #2082). You might also need apt install npm. Whatever versions of Node.js and npm you install, make sure /etc/iiab/iiab_state.yml contains the line nodejs_installed: True (add it if nec!) Finally, proceed to try installing Asterisk/FreePBX, Node-RED and/or Sugarizer. _{_#1799}
- Ubuntu 22.04.1+ LTS (Jammy Jellyfish) on PC (amd64), or more experimentally on Raspberry Pi (tutorial, install guide, wiki).
  - If you choose to install IIAB using a WiFi 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 WiFi SSID and password by editing the pre-existing file network-config 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.)
    - /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.)
    - Further details within #2379 (comment)
- If you need Moodle, Sugarizer, Internet Archive or Lokole, read below:
  - PHP 8.1 OS’s like Ubuntu 22.04, Mint 21 and Debian 12 require Moodle 4.1 LTS expected on 2022-11-28. Prior to then, if you ask IIAB to install Moodle on these OS’s, it will auto-install the latest “weekly” Moodle 4.1dev pre-release: PR #3184 PR #3382
  - As of October 2022, if you install Sugarizer (and hence MongoDB), subsequent runs of sudo iiab will be blocked by apt update emitting warnings about /etc/apt/trusted.gpg — a partial workaround (so you can at least continue installing other things) is to run: apt-key list rm /etc/apt/sources.list.d/mongodb-org.list apt-key del 90CF B1F5 Likewise run these 2 lines, if you installed roles/internetarchive: (e.g. as part of a LARGE-sized IIAB install) rm /etc/apt/sources.list.d/yarn.list apt-key del 86E5 0310 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)). If you don’t do this, 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.”
  - As of 2021-11-25, http://box.lan/lokole showed “502 Bad Gateway” : #3047
- Linux Mint 21 works very well too (it builds 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. IIAB’s Admin Console too, thanks to: PR iiab/iiab-admin-console#336
- Debian 11 (Bullseye), as was released 2021-08-14 (installer, release notes). Install tips are at PR #2582 (since Oct 2020) and #2749 (since Apr 2021).
  - CAUTION: Debian Edu (Skolelinux, #2831) is not supported at this time.
The following OS’s are theoretically possible, but may require extensive babysitting to get right: (modify /opt/iiab/iiab/scripts/local_facts.fact Lines 56-89 if necessary)
- Ubuntu 22.10 (Kinetic Kudu) was released 2022-10-20 for PC (amd64), and more experimentally for Raspberry Pi (tutorial, install guide, wiki).
  - Review Ubuntu 22.04 Kolibri/Moodle/Sugarizer issues above.
  - 2022-10-24 INSTALL TIPS: #3343 #3408
- Ubuntu 23.04 (Lunar Lobster) pre-release daily builds (for server or desktop) are expected by/around late November 2022. Its final release is expected 2023-04-20.
- Debian 12 (Bookworm) is Debian’s testing branch. Its final release is expected mid-2023. Daily builds are available for amd64. CAUTION: Debian Edu (Skolelinux, #2831) is not supported at this time. In any case, you will need to add the line VERSION_ID="12" to /etc/os-release before trying to install IIAB.
  - 2022-10-12 IMPORTANT INSTALL TIPS: #3399 (e.g. using Multipass for “instant” Debian VM’s)
  - SEE ALSO: apt-key list and apt-key del tips (in the Ubuntu 22.04 section above) as legacy signing keys in /etc/apt/* can impede sudo iiab
- 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
- Raspberry Pi Desktop for PC a.k.a. Debian Buster 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 or 16.x.y later?) and npm 7.x.y (for now)
    - sudo echo ‘nodejs_installed: True’ >> /etc/iiab/iiab_state.yml
- “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 56-89 if necessary)
- 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: http://d.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!

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