This document is a step-by-step guide on how to install and get to know Internet-in-a-Box (IIAB) software. We encourage all potential contributors to use this guide to try out IIAB!

A small compassionate act enlarges the scope of community ~ Mary Anne Radmacher

Table of Contents

1. Before You Begin
2. Requirements
3. Getting Started Examples
   1. Install IIAB on Raspberry Pi
   2. Install IIAB on an old laptop/PC
   3. Install IIAB on a Virtual Machine
4. Understanding Ansible
5. Low-Bandwidth Screen Sharing
6. Report a Bug
7. Contributing
8. Show Your Support
9. Acknowledgements

Before You Begin

IIAB (video introduction) runs on various GNU/Linux operating systems such as Raspberry Pi OS, Ubuntu, Debian, Linux Mint — and possibly also other Linux distros if you invest the effort!

You can install IIAB on Raspberry Pi 3, 3 B+, 4, 400 or an x86_64 PC/laptop. Running IIAB on the $10 Raspberry Pi Zero W or the $15 Raspberry Pi Zero 2 W is also possible, if you insert a working IIAB microSD card.

Also consider installing IIAB on an x86_64 VM (Virtual Machine), e.g. for testing purposes. On PC-like hardware especially (x86_64) note the hardware section of our FAQ for memory, storage, and network requirements.

Please avoid Docker, as our Ansible provisioning requires low-level access to the operating system.

In all cases, check out FAQ.IIAB.IO and the HOW-TO videos on Internet-in-a-Box’s YouTube channel. Also consider our upcoming milestones on GitHub.

To begin, most people should use IIAB’s 1-line installer to get the very latest, from: https://download.iiab.io

Or if you’re impatient, have a Raspberry Pi handy, and don’t mind older software, install an IIAB image direct to a microSD card (that is immediately insertable into almost any Raspberry Pi).

Conversely if you’re a traditionalist, you can install IIAB step-by-step from scratch.

Regardless: after IIAB software is installed, please be patient when downloading content over a slow Internet connection, which can sometimes take many hours indeed!

:hammer: Requirements

• Hardware: A $35+ Raspberry Pi, or a fresh x86_64 laptop/PC/VM
• OS: A very recent version of Raspberry Pi OS, Ubuntu, Linux Mint or Debian
• A very basic understanding of Linux will help!

:construction_worker: Getting Started Examples

To help new contributors get started with IIAB, we provide 3 example install paths below.

(If necessary, other platforms are also possible.)

Install IIAB on Raspberry Pi

1. Install Raspberry Pi OS onto a microSD card using the most recent 64-bit image.
2. Insert the microSD card into the Raspberry Pi and turn it on.
3. Connect your Raspberry Pi to the Internet, using Ethernet or WiFi.
   • If an Ethernet cable is not possible, and your Raspberry Pi doesn’t have an attached screen, you can set up wpa_supplicant.conf for headless WiFi.
4. Enable ssh on your Raspberry Pi if you’ll be using an ssh remote connection to your Raspberry Pi (instead of an attached screen and keyboard).
   • If so, figure out your Raspberry Pi’s IP Address (e.g. on your home’s network). Typically this is 192.168.0.x — use Raspberry Pi’s official “How to Find your [IIAB’s] IP Address” instructions or these additional tips. (Ubuntu’s own instructions for determining the Pi’s IP address are also excellent!)
5. Open a Terminal on the Raspberry Pi, using an attached screen or a remote connection (e.g. ssh pi@192.168.0.x). Then run these commands:
   1. Make sure you’re online. To verify, run: ping mit.edu
   2. Run this to install IIAB: curl iiab.io/install.txt | bash
   3. Follow the on-screen instructions carefully! Read “What services (IIAB apps) are suggested during installation?” if you want to know more about (1) SMALL, (2) MEDIUM and (3) LARGE-sized IIAB installs.
   4. You might need to run sudo iiab several times, until it completes. It might take 15 minutes, or it might take an hour or more, depending on CPU/bandwidth/disk and how you configured /etc/iiab/local_vars.yml
   5. Finally, when you see “INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE”, photograph the instructions. See also: How to Find your [IIAB’s] IP Address.
   6. Reboot by running: sudo reboot
6. Browse to your IIAB’s above-mentioned IP address (or try http://box.lan). Explore and install content onto your IIAB!

Install IIAB on an old laptop/PC

1. Most any laptop or PC from the past decade should work (verify that its CPU is x86_64, also known as amd64).
2. Install the latest Ubuntu Desktop, Ubuntu Server, Linux Mint or Debian (amd64) onto the laptop/PC.
3. Open a Terminal on the laptop/PC, to run these commands:
   1. Make sure you’re online. To verify, run: ping mit.edu
   2. Run this to install IIAB: curl iiab.io/install.txt | bash
   3. Follow the on-screen instructions carefully! Read “What services (IIAB apps) are suggested during installation?” if you want to know more about (1) SMALL, (2) MEDIUM and (3) LARGE-sized IIAB installs.
   4. You might need to run sudo iiab several times, until it completes. It might take 15 minutes, or it might take an hour or more, depending on CPU/bandwidth/disk and how you configured /etc/iiab/local_vars.yml
   5. Finally, when you see “INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE”, photograph the instructions. See also: How to Find your [IIAB’s] IP Address (even if your IIAB is not a Raspberry Pi!)
   6. Reboot by running: sudo reboot
4. Browse to your IIAB’s above-mentioned IP address (or try http://box.lan). Explore and install content onto your IIAB!

Install IIAB on a Virtual Machine

1. Download and install VirtualBox onto Windows, Mac or Linux.
   • M1 Mac Warning and Alternative Option: (December 2021)
     • VirtualBox does not run on Macs with the M1 chip. Additionally, content such as Wikipedia (all ZIM files) does not work on these Macs, no matter what virtualization product you use (Parallels, UTM or Multipass). See #3039 for more details.
     • As an alternative, if you also have a Raspberry Pi, you can install IIAB onto a microSD card using Raspberry Pi Imager. Macs with M1 chips require the Rosetta 2 emulator — you can install this by running softwareupdate --install-rosetta at the macOS Terminal command-line. Then run Raspberry Pi Imager, as outlined in IIAB Docs. See raspberrypi/rpi-imager#235 for more details.
   • Or, if using Multipass 1.10.1+ instead of VirtualBox: run snap install lxd then multipass set local.driver=lxd then multipass launch -n primary -c 2 -m 5G -d 25G --network enp1s0 then multipass shell as outlined at canonical/multipass#2537. You can immediately now run the commands in Step 4. below!
2. Download and install a Virtual Machine (VM) that contains a very recent version of Ubuntu, Debian, or Mint, e.g. from the Linux Images website. Or create your own VM by freshly installing an appropriate OS, remembering to:
   • Use VirtualBox to set the VM’s Network > Adapter 1 > Enabled Network Adapter > Attached to: Bridged Adapter, so that other devices in your home/office will be able to browse this IIAB (as the final step below).
   • Use VirtualBox to set the VM’s System > Processor > Processor(s): 2 if you want your VM to reboot more reliably.
   • Mac: You may have to open System Preferences > Security & Privacy > click on the padlock to allow VirtualBox to be installed. Follow the on-screen instructions to update the app privileges while installing.
3. Use VirtualBox to turn on (boot up) the VM.
4. Open a Terminal in the running VM, to run these commands:
   1. Make sure you’re online. To verify, run: ping mit.edu
   2. Run this to install IIAB: curl iiab.io/install.txt | bash
   3. Follow the on-screen instructions carefully! Read “What services (IIAB apps) are suggested during installation?” if you want to know more about (1) SMALL, (2) MEDIUM and (3) LARGE-sized IIAB installs.
   4. You might need to run sudo iiab several times, until it completes. It might take 15 minutes, or it might take an hour or more, depending on CPU/bandwidth/disk and how you configured /etc/iiab/local_vars.yml
   5. Finally, when you see “INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE”, photograph the instructions. See also: How to Find your [IIAB’s] IP Address (even if your IIAB is not a Raspberry Pi!)
   6. Reboot by running: sudo reboot
5. Browse to your IIAB’s above-mentioned IP address (or try http://box.lan). Explore and install content onto your IIAB!

Understanding Ansible

IIAB uses Ansible to install and configure all software packages. Ansible uses playbooks (let’s call them roles from here onwards) as human-readable instruction files, in the YAML format. An example IIAB role is 1-prep (Stage 1) here:

├── roles
│   ├── 1-prep
│   │   ├── defaults
│   │   │   └── main.yml (role variables, can also be defined in /opt/iiab/iiab/vars/default_vars.yml, and overridden by /etc/iiab/local_vars.yml)
│   │   ├── README.adoc
│   │   ├── tasks
│   │   │   ├── main.yml (actions [Ansible modules] that install this role)
│   │   │   └── ...
│   │   └── templates
│   │       ├── iiab.env.j2 (or any text file, that uses Jinja2 templating e.g. {% <variable> %}, to substitute in Ansible variable values)
│   │       └── ...
│   ├── 2-common
│   │   ├── README.adoc
│   │   ├── tasks
│   │   └── templates

Specifically, Ansible installs IIAB starting with 0-init, followed by Stages 1 to 9, and finally runs the network role:

• 0-init
• 1-prep
• 2-common
• 3-base-server
• 4-server-options
• 5-xo-services
• 6-generic-apps
• 7-edu-apps
• 8-mgmt-tools
• 9-local-addons
• network

Click on Stages 1 to 9 above for descriptions of their specific purposes.

In summary, Ansible gathers system info (using Ansible facts) to set Ansible variables, which guide IIAB’s software installation process. Execution follows a sequence of cascading steps:

1. The bash script ./iiab-install (in /opt/iiab/iiab) uses Ansible to run /opt/iiab/iiab/iiab-stages.yml

2. iiab-stages.yml calls 9+ stages (these are the numbered directories above, in /opt/iiab/iiab/roles) and then the network role. It avoids repeating any of these 9 core install stages (in case of Internet glitches etc) by keeping a counter (“STAGE”) in /etc/iiab/iiab.env (Aside: the network role can also later be run using ./iiab-network)

3. Each stage has a <role>/tasks/main.yml to invoke all needed roles and tasks.

Please refer to the IIAB Architecture and IIAB Variables pages for more detail.

Please also review “What is Ansible and what version should I use?” at FAQ.IIAB.IO

For details on how IIAB installs the very latest Ansible, see: /opt/iiab/iiab/scripts/iiab

Low-Bandwidth Screen Sharing

Live collaboration with developing countries over low-bandwidth connections is possible!

Everyone will be able to type simultaneously in the same Linux Terminal (command-line interface).

Instructions:

1. Invite people to ssh to your Internet-in-a-Box (IIAB).
   1. To simplify, ask each person to log into the same account, e.g. username iiab-admin.
   2. You can remind everyone who’s already logged into your IIAB, by running:
      sudo wall "Hi everyone! Remember to log in as username iiab-admin"
2. The screen command should already be installed. But if not, run: sudo apt install screen
   • Later you might consider the more advanced features of tmux and/or byobu.
3. Run screen -ls to see if somebody else has already started a screen session:
   • If you DO see “There is a screen on:” then run screen -x to join a pre-existing screen session.
   • If you DON’T see “There is a screen on:” then you are the 1st person to arrive — so run screen to start a screen session for everyone.
4. Everybody who’s connected can now type and run commands together!
5. Type Ctrl-a ? for help.
   • If you want tab completion during future screen sessions, run: echo "defshell -bash" >> ~/.screenrc
6. If you want to end the screen sharing session for everyone, run: exit

Report a Bug

Please post bug reports and feature requests to GitHub here:

https://github.com/iiab/iiab/issues (click New issue)

Contributing

Contributions, field reports, and feature requests are welcome!

Please also see “How can I help?” at FAQ.IIAB.IO and consider contacting us directly, Thanks!

Show Your Support

Give a ⭐️ if you like this project!

Acknowledgements

Profound thanks to Arky who inspired and wrote the original IIAB Contributors Guide in 2017.