As of December 2021, please see Internet-in-a-Box’s NEW Technical Contributors Guide !

“A small compassionate act enlarges the scope of community” - Mary Anne Radmacher -

About IIAB

Internet-in-a-Box (IIAB) runs on various GNU/Linux operating systems such as Raspberry Pi OS, Ubuntu, Debian, Linux Mint — and possibly also on CentOS, Fedora, Ubermix and DietPi if you invest the effort!

You can install Internet-in-a-Box on x86_64 PCs/laptops and Raspberry Pi 3, 3 B+, 4 or 400. Example PCs include Intel NUC and Gigabyte BRIX. A VirtualBox VM can also be used for testing purposes. Partial support is also available on OLPC laptops like the XO-1.5, XO-1.75 and XO-4. Using Docker containers however is not recommended as our Ansible provisioning system requires low-level access to the operating system.

Finally, running Internet-in-a-Box on the Raspberry Pi Zero W is also possible, if you transfer a working IIAB (microSD card) built in a Raspberry Pi 3, 3 B+ or 4.

Please see “What hardware should I use?” at FAQ.IIAB.IO and the HOW-TO videos on Internet-in-a-Box’s YouTube channel. You might also want to review Internet-in-a-Box’s upcoming milestones on GitHub.

Installation

Before you install IIAB, please refer to the hardware section of our FAQ page for memory, storage and network requirements for your platform. Also note that downloading content might take a long time on slower Internet connections.

Most all implementers should use IIAB’s 1-line installer at http://download.iiab.io

If you are a developer, consider building Internet-in-a-Box from scratch.

For more info, see also the HOW-TO videos on Internet-in-a-Box’s YouTube channel (several available as .mp4 and .webm).

Setting up a development environment

(This section uses an experimental development environment for Internet-in-a-Box. It was formerly being developed in the iiab-dev-mode repository.)

This section provide a quick setup of Internet-in-a-Box (IIAB) development environment using Vagrant. You will need a computer with virtualization enabled and git, Vagrant (2.0 or later) and VirtualBox installed.

Requirements

git
VirtualBox
Editor (Atom, Emacs, vi, etc)

Setup Instructions

Check out the repository and its submodules onto your development machine. git clone --recursive https://github.com/arky/iiab-dev-mode.git
Change directory into ‘iiab-dev-mode’ with cd iiab-dev-mode. You can update all the submodules to the latest master using git submodule foreach git pull origin master
Set up a vagrant machine with vagrant up and provision it with vagrant provision. Please select the available bridge network interface (wlan0 or eth0) that connects your host machine to the Internet.
Connect to your vagrant machine with vagrant ssh. All your local development files available as shared folder in /opt/iiab directory.
Install IIAB itself from the Ansible playbooks by following IIAB Installation instructions:

   cd /opt/iiab/iiab/scripts/
   ./ansible

   cd /opt/iiab/iiab/
   ./iiab-install

   cd /opt/iiab/iiab-admin-console/
   ./install

Hack away!
You can commit your local changes to your personal forks of (either above) Internet-in-a-Box repository and then a send pull request to the IIAB project. Once you’ve forked a repository, you change directory into that repository and set a default git remote push setting with the following command:

cd <repo> && git remote set-url --push origin git@github.com:<your_username>/<your_forked_iiab_repo_name>.git

Learn more by reading the blog post Different git Push & Pull(fetch) URLs and the Git Basics - Working with Remotes chapter of Scott Chacon and Ben Straub’s “Git Pro” book.
Once you are done, you can stop your vagrant machine with vagrant halt or remove it completely with vagrant destroy.

Ansible

Internet-in-a-Box uses Ansible (similar to Puppet, but acquired by Red Hat in October 2015) to install and configure all software packages. Ansible uses playbooks as human-readable instruction files in YAML format. Playbooks are divided into hosts, roles and tasks.

├── roles
│   ├── 1-prep
│   │   ├── defaults
│   │   │   └── main.yml (variables defined at /opt/iiab/iiab/vars/default_vars.yml can be overridden by /etc/iiab/iiab/local_vars.yml)
│   │   ├── README.rst
│   │   ├── tasks
│   │   │   └── main.yml (actions that install this role)
│   │   └── templates
│   │       └── <text files where Ansible variables are substituted, using jinja2 templating e.g. {% <variable> %}>
│   ├── 2-common
│   │   ├── README.rst
│   │   ├── tasks
│   │   └── templates

Specifically, Ansible installs Internet-in-a-Box starting with 0-init, followed by Stages 1 to 9, and finally runs the network stage: - 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.

At runtime (to build up your Internet-in-a-Box server) Ansible gathers system information making it available (as ‘facts’) and combines this with Ansible ‘variables’ to guide the installation process. The execution follows a sequence of cascading steps:

Bash script ./iiab-install uses Ansible to run /opt/iiab/iiab/iiab-stages.yml
iiab-stages.yml calls 9+ aggregate roles (AKA 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)
Each aggregate role AKA stage has a <role>/tasks/main.yml (formerly <role>/meta/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.html

Take a look inside IIAB’s script that installs the very latest Ansible release: https://github.com/iiab/iiab/blob/master/scripts/ansible

Debugging

Here are few strategies for debugging problems during the Internet-in-a-Box installation.

When a installation task fails, Ansible halts printing out a descriptive error message to the screen. This error information is also written to iiab-install.log file within /opt/iiab/iiab. (Look through logs to check if any preceding line contains the error).
When an installation succeeds, the last lines printed on the screen will look like the following (failed=0):

   PLAY RECAP *********************************************************************
   127.0.0.1                  : ok=405  changed=125  unreachable=0    failed=0

Search through the Ansible playbooks using egrep -rn <string from the failing step> /opt/iiab/iiab/roles to find the failed task.
You can add additional debug print statements to Ansible playbooks for debugging the problem.
Talk to us or report a bug using the information below.

Please refer to Ansible playbook documentation for more information.

Reporting Bugs

You can file bug reports on GitHub:

Sign up for a GitHub account
Go to IIAB’s issue tracker on GitHub
Search for existing issues using the search field
If you don’t find any similar issues, file a new issue!

Please consider providing a descriptive title, your operating system information, error messages and steps to reproduce the issue.

Get in touch

Join our technology and learning/design mailing lists
Join our weekly calls which are typically held 10AM to Noon NYC Time, most every Thursday
Read “What are the best places for community support?” and “How can I help?” within our Frequently Asked Questions (FAQ.IIAB.IO)

For more information on how to contribute, please see “How can I help?” at FAQ.html and consider contacting us directly, Thanks!