Skip to content

Latest commit

 

History

History
167 lines (116 loc) · 11.1 KB

CONTRIBUTING.deprecated.md

File metadata and controls

167 lines (116 loc) · 11.1 KB
Raw

SEE THE NEW
github.com/iiab/iiab/wiki/IIAB-Contributors-Guide

THANKS! EVERYTHING BELOW IS DEPRECATED.

Contributing to Internet-in-a-Box (IIAB)

Internet-in-a-Box runs on various GNU/Linux operating systems such as Raspbian, Ubuntu, Debian, CentOS and Fedora.

You can install Internet-in-a-Box on x86_64 PCs/laptops and Raspberry Pi 3 (or 3 B+). Example PC's include Intel NUC and Gigabyte BRIX. Partial support is also available on OLPC laptops like the XO-1.5, XO-1.75 and XO-4. A VirtualBox VM can also be used for testing purposes. 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) that was built up inside a Raspberry Pi 3 (or 3 B+).

Please refer to IIAB Platforms for more information.

Internet-in-a-Box uses Ansible (acquired by Red Hat in October 2015, similar to Puppet) 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 (lowest precedence variable definitions, overridden by <repo_root>/vars/default_vars.yml, overridden by /etc/iiab/local_vars.yml)
│   │   ├── README.rst
│   │   ├── tasks
|   |   |    ├──main.yml (specifies the actions to 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:

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:

  1. Bash script ./iiab-install uses Ansible to run /opt/iiab/iiab/iiab-stages.yml

  2. 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)

  3. 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 information.

Installation

Before you start the installation, please refer to the hardware section of the 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 implementers should use IIAB's 1-line installer at http://download.iiab.io (click on the version number, e.g. 6.6).

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

Please refer to the IIAB Installation page for more information.

Setting up development environment

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

This section provides a quick setup of the 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

Setup Instructions

  1. Check out the repository and its submodules onto your development machine. git clone --recursive [email protected]:arky/iiab-dev-mode.git

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

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

  4. Connect to your vagrant machine with vagrant ssh. All your local development files are available through shared folders in the /opt/iiab directory.

  5. Install IIAB itself from the Ansible playbooks by following IIAB Installation instructions:

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

   cd /opt/iiab/iiab/
   ./runansible

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

   cd /opt/iiab/iiab-menu/
   ./cp-menus

  1. Hack away!

  2. You can commit your local changes to your personal forks of the Internet-in-a-Box repository and then send pull requests 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 [email protected]:<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.

  3. Once you are done, you can stop your vagrant machine with vagrant halt or remove it completely with vagrant destroy.

Debugging

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

  • When an installation task fails, Ansible halts printing out a descriptive error message to the screen. This error information is also written to a 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.

Testing your code with Travis CI

To maintain the quality of the Internet-in-a-Box (IIAB) code, we use Travis Continuous Integration (CI) build infrastructure. Travis CI does tests to ensure the code syntax is correct and the code is formatted properly using ansible syntax checker, ansible-lint and ansible-review tools. The results of Travis CI Internet-in-a-Box (IIAB) could be seen here.

Every pull request [was] automatically tested by Travis CI. The results of these tests [were] added to the pull request. This aids Internet-in-a-Box (IIAB) developers in reviewing the quality of the code in a pull request [this approach is currently on hold as of July 2018 — if it's tuned up, this or any similar CI/CD alternatives would be welcome!]

To test your forked repository of Internet-in-a-Box (IIAB) code, you have to enable automatic build tests in your Travis-ci.org profile page.

  • Login to Travis-ci.org using your Github account.
  • Go to your Travis CI profile page and enable the repository you want to build.
  • The builds will start whenever a new commit is pushed to your repository.

Please refer to Travis CI documentation for more information.

Reporting Bugs

You can file bug reports on GitHub:

  • Sign up for a GitHub account
  • Go to the 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