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 laptop/PC. 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: 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 laptop, PC or Mac must have a 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.5+ 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, or on Mac: Command + 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 NEXT and confirm! Writing the OS to your microSD card will take a few minutes.
   2. OR USE A RASPBERRY PI:
      • Your Raspberry Pi MUST have an attached keyboard, mouse, screen AND Ethernet cable connected to live Internet.
        • Update your Raspberry Pi's bootloader (especially if it's older than 2023!)
        • 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.5+ should appear on screen.
        • OPTIONALLY use Advanced Options (gear button ⚙️ in the bottom-right, or equivalently Ctrl + Shift + X, or on Mac: Command + 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 NEXT and confirm! Writing the OS to your microSD card will take a few minutes.
      • 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 — so the Raspberry Pi's internal IIAB hotspot can be created 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 "Find the IP address of your [IIAB] Raspberry Pi" instructions or these additional tips. (Ubuntu's own instructions for determining the Pi’s IP address are also useful!)
4. Open a Terminal on the Raspberry Pi, using an attached screen or a remote connection (e.g. ssh [email protected]), 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. The Raspberry Pi might reboot in the first few minutes, after applying system/security updates.
   5. Run sudo iiab as many times as necessary, 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
   6. Finally, when you see "INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE", photograph the instructions. See also: Find the IP address of your [IIAB] Raspberry Pi
   7. Reboot your IIAB (Raspberry Pi).
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. Your laptop/PC might reboot in the first few minutes, after applying system/security updates.
   5. Run sudo iiab as many times as necessary, 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
   6. Finally, when you see "INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE", photograph the instructions. See also: Find the IP address of your [IIAB] Raspberry Pi (even if your IIAB is not a Raspberry Pi!)
   7. Reboot your IIAB (laptop/PC).
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 (virtual machine) methods work well on Linux, Windows Pro and Macs: (on Windows Home, try VirtualBox)
   • Install Multipass to get moving quickly:
     • Create an Ubuntu Server 24.04 VM:
       • On Linux: Set up a basic VM, by running multipass launch -n box -c 2 -m 2G -d 25G OR if you want your VM to also get an IP Address like 192.168.0.x from your home router, be cautious with canonical/multipass#2537 and run these 2 commands run as root BEFORE you create/launch the VM: snap install lxd then multipass set local.driver=lxd. If so, confirm your PC's gateway interface is enp1s0 by running multipass networks, and finally create the VM by running: multipass launch -n box -c 2 -m 2G -d 25G --network enp1s0
       • On Windows Pro: Set up a basic VM, by running multipass launch -n box -c 2 -m 2G -d 25G (getting your VM to also have an IP Address like 192.168.0.x from your home router is tricky on Windows, but if you want to try: run multipass networks and read canonical/multipass#2500). IN ALL CASES: Keep the VM named box on Windows, to simplify your life! Why? As of 2024, Multipass still requires that /etc/hostname (within any VM on Windows) never deviate from the original name of the VM (#255, #3346), otherwise the VM can never be rebooted!
       • On Mac: Confirm your gateway interface is en0 (e.g. by running multipass networks) and if so create the VM by running multipass launch -n box -c 2 -m 2G -d 25G --network en0 (your VM should also get an IP Address like 192.168.0.x from your home router).
     • Run multipass shell box to shell into the VM you just created.
     • Jump to Step 2. below!
   • Or install VirtualBox:
     • 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 > Enable 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.
       • On 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.
     • Use VirtualBox to turn on (boot up) the VM.
2. At the command-line in the running VM (open a Terminal if necessary!) 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. The VM might reboot in the first few minutes, after applying system/security updates.
   5. Run sudo iiab as many times as necessary, 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
   6. Finally, when you see "INTERNET-IN-A-BOX (IIAB) SOFTWARE INSTALL IS COMPLETE", photograph the instructions. See also: Find the IP address of your [IIAB] Raspberry Pi (even if your IIAB is not a Raspberry Pi!)
   7. Reboot your IIAB (VM).
3. 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 the 10 Stages and network role 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.