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

:bookmark_tabs: 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

:goggles: 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, 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, 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

: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 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) 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) 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!
  4. Open a Terminal on the Raspberry Pi, using an attached screen or a remote connection (e.g. ssh username@192.168.0.x), 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!

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. 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!

Install IIAB on a Virtual Machine

  1. Both these VM (virtual machine) methods work well on Linux, Windows Pro and Macs: (on Windows Home, try VirtualBox)
  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!

:female_detective: 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:

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

:technologist: 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
  3. Run screen -ls to see if somebody else has already started a screen session:
  4. Everybody who’s connected can now type and run commands together!
  5. Type Ctrl-a ? for help.
  6. If you want to end the screen sharing session for everyone, run: exit
  7. Optional: advanced tips.

:bowtie: Report a Bug

Please post bug reports and feature requests to GitHub here:

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

:mechanic: 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!

:open_hands: Show Your Support

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

Acknowledgements

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