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!

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

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, 5 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.

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

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!

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

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

(If necessary, other platforms are also possible.)

1. Install 64-bit Raspberry Pi OS onto a microSD card:
   1. IF YOU HAVE A PC, LAPTOP OR MAC:
      • Your PC, laptop or Mac must have a slot for built-in slot for SD cards — or an external USB card reader (typically $10).
        • Insert a blank/new microSD card.
      • Install Raspberry Pi Imager 1.8.1+ onto your computer, then run the program.
      • Use Raspberry Pi Imager's Advanced Options (gear button ⚙️ in the bottom-right, or equivalently Ctrl-Shift-X) to pre-configure your microSD card:
        1. Enable SSH
        2. Set username and password
        3. IF AN ETHERNET CABLE (to the Internet) IS ABSOLUTELY NOT AVAILABLE FOR YOUR Raspberry Pi, then "Configure wireless LAN" (enter a valid Wi-Fi SSID and password).
      • Install 64-bit Raspberry Pi OS onto your microSD card:
        1. Click CHOOSE OS to pick any version of 64-bit Raspberry Pi OS.
        2. Click CHOOSE STORAGE to specify which microSD card it should write to.
        3. Click WRITE and wait for it to complete!
   2. OR USE A RASPBERRY PI:
      • Your Raspberry Pi MUST have an attached keyboard, mouse, screen AND Ethernet cable connected to live Internet.
        • Insert a blank/new microSD card into your Raspberry Pi.
      • Hold down the SHIFT key as you turn it on. Within about 4 minutes, Raspberry Pi Imager 1.8.1+ should appear on screen.
        • OPTIONALLY use Advanced Options (gear button ⚙️ in the bottom-right, or equivalently Ctrl-Shift-X) to pre-configure your microSD card: (1) Enable SSH (2) Set username and password.
      • Install 64-bit Raspberry Pi OS onto your microSD card:
        1. Click CHOOSE OS to pick any version of 64-bit Raspberry Pi OS.
        2. Click CHOOSE STORAGE to specify which microSD card it should write to.
        3. Click WRITE and wait for it to complete!
      • Reboot to launch the OS, and skip ahead to Step 4.
2. Insert the microSD card into the Raspberry Pi and turn it on.
3. Connect your Raspberry Pi to the Internet — using an Ethernet cable if possible — as this allows an internal IIAB hotspot to be set up without confusion!
   • If Ethernet is impossible in your situation, use Wi-Fi instead (to connect your Raspberry Pi to the Internet).
   • If your Raspberry Pi is "headless", figure out its IP Address (e.g. on your home's network) so you can ssh into it. 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!)
4. Open a Terminal on the Raspberry Pi, using an attached screen or a remote connection (e.g. ssh username@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/temperature 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
5. Browse to your IIAB's above-mentioned IP address (or try http://box.lan). Explore and install content onto your IIAB!

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!

1. Both these VM methods work on Linux, Windows and (some!) Macs:
   • Install Multipass to get moving quickly:
     • Set up a basic Ubuntu Server 22.04 VM, by running multipass launch -n primary -c 2 -m 2G -d 25G then multipass shell
     • Or, if you want your VM to also have an IP Address like 192.168.0.x, instead run these commands (as root) per canonical/multipass#2537: snap install lxd then multipass set local.driver=lxd then multipass launch -n primary -c 2 -m 2G -d 25G --network enp1s0 (e.g. if your gateway interface is enp1s0) then multipass shell
     • Either way, jump to Step 4. below!
   • Or download and install VirtualBox — noting its M1/M2 Mac Warning:
     • Prior to October 2022, VirtualBox did not run on Macs with M1 or M2 chips. As of 2023, the VirtualBox M1/M2 warning (above) still applies (but can possibly be ignored?!)
     • CAUTION: Content such as Wikipedia (all ZIM files) does not yet work on M1/M2 Macs, no matter what virtualization product you use (Multipass, VirtualBox, Parallels or UTM). See #3039 for more details.
     • Finally if you also have a Raspberry Pi, one alternative (bypassing all other steps below) is to very directly install a pre-built IIAB image onto any microSD card (instead of a VM, done!)
     • CAUTION: The catch (similar to above!) is that Raspberry Pi Imager may not run well on M1/M2 Macs. See raspberrypi/rpi-imager#235 for details, e.g. if necessary Macs with M1/M2 chips can run the Rosetta 2 emulator. (If so you can install this by running softwareupdate --install-rosetta at the macOS Terminal command-line, and then try running Raspberry Pi Imager via emulation.)

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!

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/ansible

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
7. Optional: advanced tips.

Please post bug reports and feature requests to GitHub here:

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

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!

Give a ⭐️ (top of https://github.com/iiab/iiab) if you like this project!

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