mirror of
https://github.com/iiab/iiab.git
synced 2025-03-09 15:40:17 +00:00
commit
fdf2cca181
8 changed files with 163 additions and 15 deletions
143
CONTRIBUTING.md
Normal file
143
CONTRIBUTING.md
Normal file
|
@ -0,0 +1,143 @@
|
||||||
|
Contributing to Internet-in-a-Box (IIAB)
|
||||||
|
=======================================
|
||||||
|
Internet-in-a-Box runs on various GNU/Linux operating systems such as Fedora, Ubuntu, Debian, CentOS and Raspbian.
|
||||||
|
|
||||||
|
You can install Internet-in-a-Box on most late model desktop and laptop computers. It also supports Intel NUC, Intel Gigabyte BRIX, OLPC XO-1.5, XO-1.75, XO-4, Raspberry Pi 2 and Raspberry Pi 3. A VirtualBox VM can also used for testing purposes. Using Docker containers however is not recommended as our Ansible provisioning system requires low-level access to the operating system.
|
||||||
|
|
||||||
|
Please refer to [IIAB Platforms](https://github.com/iiab/iiab/wiki/IIAB-Platforms) for more information.
|
||||||
|
|
||||||
|
Internet-in-a-Box uses [Ansible](https://www.ansible.com/) infrastructure automation tool to deploy and configure all software packages. Ansible uses [playbooks](http://docs.ansible.com/ansible/latest/playbooks.html) a 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 ./vars/local_vars.yml.
|
||||||
|
│ │ ├── README.rst
|
||||||
|
│ │ ├── tasks
|
||||||
|
| | | ├──main.yml (specifies the actions to install this role
|
||||||
|
│ │ └── templates
|
||||||
|
| | | ├<(text files where ansible variables are substituted, specified via {% <variable> %} containers-(jinja2 language).
|
||||||
|
│ ├── 2-common
|
||||||
|
│ │ ├── README.rst
|
||||||
|
│ │ ├── tasks
|
||||||
|
│ │ └── templates
|
||||||
|
```
|
||||||
|
At runtime, Ansible gathers system information and makes it available (called 'facts') and combines this with playbook defined 'variables' to guide the installation process. The execution follows a sequence of cascading steps:
|
||||||
|
|
||||||
|
1. Bash script `./runansible` follows instructions in `iiab.yml` in the root directory.
|
||||||
|
|
||||||
|
2. `iiab.yml` calls 9 aggregate roles (the numbered directories under `./roles/`).
|
||||||
|
|
||||||
|
3. Each aggregate role has a `<role>/meta/main.yml` which calls the individual named roles.
|
||||||
|
|
||||||
|
Please refer to the [IIAB Architecture](https://github.com/iiab/iiab/wiki/IIAB-Architecture) and [IIAB Variables]( https://github.com/iiab/iiab/wiki/IIAB-Variables) pages for more information.
|
||||||
|
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
Before you start the installation please refer to the [hardware section of FAQ](http://wiki.laptop.org/go/IIAB/FAQ#What_hardware_should_I_use.3F) page for memory, storage and network requirements for your platform. Also note that downloading content might take a long time on slower Internet connections.
|
||||||
|
|
||||||
|
If you are a developer, please consider [building Internet-in-a-Box from scratch](https://github.com/iiab/iiab/wiki/IIAB-Installation#do-everything-from-scratch).
|
||||||
|
|
||||||
|
Please refer to the [IIAB Installation](https://github.com/iiab/iiab/wiki/IIAB-Installation) page for more information.
|
||||||
|
|
||||||
|
Setting up development environment
|
||||||
|
===================================
|
||||||
|
( This section uses experimental development environment for Internet-in-a-Box. It is being developed in the [iiab-dev-mode repository](https://github.com/arky/iiab-dev-mode). )
|
||||||
|
|
||||||
|
This section provide a quick setup of Internet-in-a-Box (IIAB) development environment using [Vagrant](https://www.vagrantup.com/). You will need a computer with [virtualization enabled](https://www.virtualbox.org/manual/UserManual.html) and git, Vagrant (2.0 or later) and [VirtualBox](https://www.virtualbox.org/) installed.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
* git
|
||||||
|
* [Vagrant (2.0 or later)](https://www.vagrantup.com/)
|
||||||
|
* [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
|
||||||
|
* Editor ([Atom](www.atom.io), Emacs, vi, etc)
|
||||||
|
|
||||||
|
## Setup Instructions
|
||||||
|
1. Check out the repository and its submodules onto your development machine.
|
||||||
|
`git clone --recursive git@github.com:arky/iiab-dev-mode.git`
|
||||||
|
|
||||||
|
2. Change directory into 'iiab-dev-mode' with `cd iiab-dev-mode`. You can update all the submodules to 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 available as shared folder in `/opt/iiab` directory.
|
||||||
|
|
||||||
|
5. Install IIAB itself from the Ansible playbooks by following [IIAB Installation](https://github.com/iiab/iiab/wiki/IIAB-Installation#do-everything-from-scratch) 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
|
||||||
|
```
|
||||||
|
6. Hack away!
|
||||||
|
|
||||||
|
7. You can commit your local changes to your personal forks of Internet-in-a-Box repository and then send pull request to IIAB project. Once you forked a repository, you change directory into that repository and setting 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 blog post [Different git Push & Pull(fetch) URLs](http://blog.yuriy.tymch.uk/2012/05/different-git-push-pullfetch-urls.html) and the [Git Basics - Working with Remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) chapter of Scott Chacon and Ben Straub's "Git Pro" book.
|
||||||
|
|
||||||
|
8. Once you are done, you can stop your vagrant machine with `vagrant halt` or remove it completely with `vagrant destroy`.
|
||||||
|
|
||||||
|
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](http://docs.ansible.com/ansible/latest/debug_module.html) to Ansible playbooks for debugging the problem.
|
||||||
|
* Talk to us or report a bug using the information below.
|
||||||
|
|
||||||
|
Please refer to [Ansible playbook documentation](http://docs.ansible.com/ansible/latest/playbooks.html) 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)](https://travis-ci.org) 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](https://travis-ci.org/iiab/iiab).
|
||||||
|
|
||||||
|
Every pull request is automatically tested by Travis CI. The results of these tests are added to the pull request. This aids Internet-in-a-Box (IIAB) developers in reviewing the quality of the code in a pull request.
|
||||||
|
|
||||||
|
To test your forked repository of Internet-in-a-Box (IIAB) code. You have to enable automatic build tests in your [Travis-ci.org](https://travis-ci.org) profile page.
|
||||||
|
|
||||||
|
* Login to [Travis-ci.org](https://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](https://docs.travis-ci.com/user/getting-started/) for more information.
|
||||||
|
|
||||||
|
Reporting Bugs
|
||||||
|
==============
|
||||||
|
|
||||||
|
You can file bug reports on [GitHub](https://github.com/):
|
||||||
|
|
||||||
|
* Sign up for a [GitHub](https://github.com/) account
|
||||||
|
* Go to the [issue tracker on GitHub](https://github.com/iiab/iiab/issues)
|
||||||
|
* 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](http://lists.laptop.org/listinfo/server-devel) and [learning design](https://groups.google.com/group/unleashkids) mailing lists
|
||||||
|
* Join our [live calls](http://minutes.iiab.io) most Mondays and Thursday
|
||||||
|
* Join us on IRC live chat: [#schoolserver](https://webchat.freenode.net/?channels=#schoolserver) on [freenode]( https://www.freenode.net/)
|
||||||
|
* Post an idea or question to our [community forums](http://iiab.io/)
|
||||||
|
* Read our Frequently Asked Questions ([FAQ.IIAB.IO](http://FAQ.IIAB.IO))
|
|
@ -1,52 +1,53 @@
|
||||||
- name: Checking for ifcfg-WAN file - Can Fail
|
- name: Checking for ifcfg-WAN file - Can Fail
|
||||||
stat: path=/etc/sysconfig/network-scripts/ifcfg-WAN
|
stat: path=/etc/sysconfig/network-scripts/ifcfg-WAN
|
||||||
register: has_ifcfg_WAN
|
|
||||||
when: not first_run
|
when: not first_run
|
||||||
|
register: has_ifcfg_WAN
|
||||||
|
ignore_errors: True
|
||||||
|
|
||||||
- name: Setting ifcfg-WAN True
|
- name: Setting ifcfg-WAN True
|
||||||
set_fact:
|
set_fact:
|
||||||
has_WAN: True
|
has_WAN: True
|
||||||
when: has_ifcfg_WAN.stat is defined and has_ifcfg_WAN.stat.exists
|
when: not first_run and has_ifcfg_WAN.stat.exists
|
||||||
|
|
||||||
# DETECT -- gateway and wireless
|
# DETECT -- gateway and wireless - Can Fail
|
||||||
- name: Get a list of slaves from previous config - Can Fail
|
- name: Get a list of slaves from previous config - Can Fail
|
||||||
shell: "egrep -rn BRIDGE=br0 /etc/sysconfig/network-scripts/ifcfg-* | gawk -F'[-:]' '{print $3}'"
|
shell: "egrep -rn BRIDGE=br0 /etc/sysconfig/network-scripts/ifcfg-* | gawk -F'[-:]' '{print $3}'"
|
||||||
|
when: not first_run
|
||||||
register: ifcfg_slaves
|
register: ifcfg_slaves
|
||||||
ignore_errors: True
|
ignore_errors: True
|
||||||
changed_when: False
|
changed_when: False
|
||||||
when: not first_run
|
|
||||||
|
|
||||||
# returns list of paths
|
# returns list of paths
|
||||||
- name: Find gateway config based on device
|
- name: Find gateway config based on device - Can Fail
|
||||||
shell: "egrep -rn {{ device_gw }} /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}'"
|
shell: "egrep -rn {{ device_gw }} /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}'"
|
||||||
|
when: not first_run and device_gw != "none"
|
||||||
register: ifcfg_gw_device
|
register: ifcfg_gw_device
|
||||||
ignore_errors: True
|
ignore_errors: True
|
||||||
changed_when: False
|
changed_when: False
|
||||||
when: not first_run and device_gw != "none"
|
|
||||||
|
|
||||||
# last match wins
|
# last match wins
|
||||||
- name: Setting has ifcfg gw based on device if found
|
- name: Setting has ifcfg gw based on device if found
|
||||||
set_fact:
|
set_fact:
|
||||||
has_ifcfg_gw: "{{ item|trim }}"
|
has_ifcfg_gw: "{{ item|trim }}"
|
||||||
ignore_errors: True
|
|
||||||
when: ifcfg_gw_device.stdout_lines is defined and item|trim != "" and item|trim != "/etc/sysconfig/network-scripts/ifcfg-LAN"
|
when: ifcfg_gw_device.stdout_lines is defined and item|trim != "" and item|trim != "/etc/sysconfig/network-scripts/ifcfg-LAN"
|
||||||
with_items:
|
with_items:
|
||||||
- "{{ ifcfg_gw_device.stdout_lines }}"
|
- "{{ ifcfg_gw_device.stdout_lines }}"
|
||||||
|
ignore_errors: True
|
||||||
|
|
||||||
# returns path
|
# returns path
|
||||||
- name: Find active gateway config based on macaddress - Can Fail
|
- name: Find active gateway config based on macaddress - Can Fail
|
||||||
shell: "egrep -irn {{ ansible_default_ipv4.macaddress }} /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}' | head -n 1"
|
shell: "egrep -irn {{ ansible_default_ipv4.macaddress }} /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}' | head -n 1"
|
||||||
|
when: ansible_default_ipv4.gateway is defined
|
||||||
register: ifcfg_gw_mac
|
register: ifcfg_gw_mac
|
||||||
ignore_errors: True
|
ignore_errors: True
|
||||||
changed_when: False
|
changed_when: False
|
||||||
when: ansible_default_ipv4.gateway is defined
|
|
||||||
|
|
||||||
- name: Set has ifcfg gw based on on macaddress if found
|
- name: Set has ifcfg gw based on on macaddress if found
|
||||||
set_fact:
|
set_fact:
|
||||||
has_ifcfg_gw: "{{ ifcfg_gw_mac.stdout|trim }}"
|
has_ifcfg_gw: "{{ ifcfg_gw_mac.stdout|trim }}"
|
||||||
when: ifcfg_gw_mac.changed and ifcfg_gw_mac.stdout != ""
|
when: ifcfg_gw_mac is defined and ifcfg_gw_mac.changed and ifcfg_gw_mac.stdout != ""
|
||||||
|
|
||||||
# could use something else
|
# could use something else - Can Fail
|
||||||
- name: Find wifi gateway config if present - Can Fail
|
- name: Find wifi gateway config if present - Can Fail
|
||||||
shell: egrep -rn ESSID /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}' | gawk -F '/' '{print $5}'
|
shell: egrep -rn ESSID /etc/sysconfig/network-scripts/ifcfg* | gawk -F ':' '{print $1}' | gawk -F '/' '{print $5}'
|
||||||
register: ifcfg_WAN_wifi
|
register: ifcfg_WAN_wifi
|
||||||
|
@ -62,9 +63,9 @@
|
||||||
|
|
||||||
- name: Finding device for wifi AP gateway - Can Fail
|
- name: Finding device for wifi AP gateway - Can Fail
|
||||||
shell: egrep -rn DEVICE /etc/sysconfig/network-scripts/{{ has_wifi_gw }} | gawk -F '=' '{print $2}'
|
shell: egrep -rn DEVICE /etc/sysconfig/network-scripts/{{ has_wifi_gw }} | gawk -F '=' '{print $2}'
|
||||||
|
when: has_wifi_gw != "none" and has_ifcfg_gw != "none"
|
||||||
register: AP_device
|
register: AP_device
|
||||||
ignore_errors: True
|
ignore_errors: True
|
||||||
when: has_wifi_gw != "none" and has_ifcfg_gw != "none"
|
|
||||||
|
|
||||||
- name: Setting wifi device
|
- name: Setting wifi device
|
||||||
set_fact:
|
set_fact:
|
||||||
|
@ -78,4 +79,3 @@
|
||||||
# changed_when: False
|
# changed_when: False
|
||||||
# ignore_errors: True
|
# ignore_errors: True
|
||||||
# when: num_lan_interfaces >= "1" or iiab_wireless_lan_iface != "none"
|
# when: num_lan_interfaces >= "1" or iiab_wireless_lan_iface != "none"
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
dependencies:
|
dependencies:
|
||||||
|
- { role: home-page, tags: ['home-page'] }
|
||||||
- { role: sshd, tags: ['services','sshd','base'] }
|
- { role: sshd, tags: ['services','sshd','base'] }
|
||||||
- { role: network, tags: ['services','base','network'] }
|
- { role: network, tags: ['services','base','network'] }
|
||||||
- { role: postgresql, tags: ['services','postgresql','base'], when: postgresql_install }
|
- { role: postgresql, tags: ['services','postgresql','base'], when: postgresql_install }
|
||||||
|
|
|
@ -7,7 +7,7 @@
|
||||||
|
|
||||||
- name: Install admin home page into apache2
|
- name: Install admin home page into apache2
|
||||||
template: src=iiab-home-page.conf
|
template: src=iiab-home-page.conf
|
||||||
dest=/etc/{{ apache_config_dir }}/iiab-home-page.conf
|
dest=/etc/{{ apache_config_dir }}/iiab-home-page.conf
|
||||||
|
|
||||||
- name: Enable the home page
|
- name: Enable the home page
|
||||||
file: src=/etc/{{ apache_config_dir }}/iiab-home-page.conf
|
file: src=/etc/{{ apache_config_dir }}/iiab-home-page.conf
|
|
@ -146,8 +146,6 @@
|
||||||
tags:
|
tags:
|
||||||
- base
|
- base
|
||||||
|
|
||||||
- include: home-page.yml
|
|
||||||
|
|
||||||
- name: place the script to generate home pages
|
- name: place the script to generate home pages
|
||||||
template: src=refresh-wiki-docs.sh
|
template: src=refresh-wiki-docs.sh
|
||||||
dest=/usr/bin/iiab-refresh-wiki-docs
|
dest=/usr/bin/iiab-refresh-wiki-docs
|
||||||
|
|
|
@ -71,6 +71,12 @@
|
||||||
osm_path: "{{ osm_venv }}/lib/python2.7/site-packages/iiab"
|
osm_path: "{{ osm_venv }}/lib/python2.7/site-packages/iiab"
|
||||||
when: osm_enabled and is_debuntu
|
when: osm_enabled and is_debuntu
|
||||||
|
|
||||||
|
- name: All - Point wsgi to virtual environment
|
||||||
|
lineinfile: dest={{ osm_venv }}/bin/iiab.wsgi
|
||||||
|
regexp="path_to_virtualenv = None"
|
||||||
|
line="path_to_virtualenv = '/usr/local/osm'"
|
||||||
|
state=present
|
||||||
|
|
||||||
- name: All - Copy IIAB config file
|
- name: All - Copy IIAB config file
|
||||||
template: backup=no
|
template: backup=no
|
||||||
src=osm.conf.j2
|
src=osm.conf.j2
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue