INSTALL.txt

Internet-in-a-Box Installation
==============================

While the complete dataset for the Internet-in-a-Box project is over 700 GB,
you can install the 500 MB QuickStart Sampler dataset to try the software
without needing the full dataset.

There are several methods to install and run Internet-in-a-Box (IIAB).

For installation: you can install IIAB as a Python package using the Python
package manager pip.  Or you can install from source using git.

To run: you can run IIAB as a stand-alone server, or you can integrate
it with your Apache installation using WSGI as a gateway.


Quick Start
-----------

1. Install the Python package manager, pip, and the lzma library:

    Ubuntu/Debian:
    sudo apt-get install python-pip gcc python-dev liblzma-dev

    Fedora/CentOS:
    sudo yum install python-pip gcc python-devel xz-devel


2. Install Internet-in-a-Box and its dependencies (on Fedora, use 'python-pip'
instead of 'pip')

    sudo pip install Internet-in-a-Box


3. Download the QuickStart Sampler dataset and untar in root filesystem (or another 
location of your choice)
    cd /
    sudo wget http://downloads.internet-in-a-box.org/IIAB_QuickStart_Sampler_20130809.tgz
    sudo tar xvzf IIAB_QuickStart_Sampler_20130809.tgz

*Refer to the section 'Dataset Location' on specifying another directory.

4. Run the stand-alone server from /usr/local/bin, where iiab-server is installed.
    iiab-server


5. Point your web browser to http://localhost:25000/iiab


ALTERNATIVE: Installation from yum repository on Fedora 18 or OLPC OS
---------------------------------------------------------------------

RPM packages are available for Fedora 18 and OLPC OS 13.1

1. Run as su.

2. Configure Internet-in-a-Box repository

cat <<EOF >/etc/yum.repos.d/iiab.repo
[iiab]
name=Internet-in-a-Box
baseurl=http://downloads.internet-in-a-box.org/fedora/18
enabled=1
gpgcheck=0
EOF

3. Install Internet-in-a-Box from Yum

    yum --nogpgcheck install Internet-in-a-Box

4. Follow instructions 3 - 5 from Quick Start section above, or 
start from the beginning of the WSGI configuration section below.


ALTERNATIVE: Installation from Git Sources
----------------------------------------------------------------------

Recommended for developers.

1. Install pip

    Ubuntu/Debian:
    sudo apt-get install python-pip gcc python-dev liblzma-dev git

    Fedora/CentOS:
    sudo yum install python-pip python-devel gcc git xz-devel


2. Clone Internet-in-a-Box from github

    git clone https://github.com/braddockcg/internet-in-a-box


3. Install dependencies
    (use python-pip instead of pip if in Fedora)

    cd internet-in-a-box
    sudo pip install -r requirements.txt


4. Download and untar the QuickStart Sampler dataset
    sudo wget http://downloads.internet-in-a-box.org/IIAB_QuickStart_Sampler_20130809.tgz
    sudo tar xvzf IIAB_QuickStart_Sampler_20130809.tgz


5. Run stand-alone server

    ./iiab-server


6. Point your web browser to http://localhost:25000/iiab


7. (OPTIONAL) Install IIAB to system

    cd internet-in-a-box
    python setup.py install


(OPTIONAL) Installation in a Virtual Environment
------------------------------------------------

By installing in a Python virtual environment, you will completely isolate
IIAB's python dependencies and can install them without being root.

1. Install virtualenv and dependencies

Because we will be building our python modules from scratch, we require a few
additional dependencies.

    Ubuntu/Debian:
    sudo apt-get install python-virtualenv

    Fedora/CentOS:
    sudo yum install python-virtualenv xz-devel


2. Create a virtualenv directory and activate it

    virtualenv venv
    . venv/bin/activate

3. Follow previous instructions to install IIAB using pip or git as normal
(except you don't need sudo).  IIAB and all python dependencies will be
installed into the venv/ directory

You can install IIAB as a WSGI service from within a virtualenv.  To do so,
you must edit the "path_to_virtualenv" variable at the top of the iiab.wsgi
file.


Installation as an Apache WSGI Service
--------------------------------------

IIAB can be installed under Apache to run as a WSGI service.  In this case, you
will not need to start IIAB as a stand-alone server - Apache's mod_wsgi will
launch instances of the IIAB software as needed to respond to HTTP requests.

Running IIAB as a WSGI service requires two additional Apache modules: mod_wsgi
and mod_sendfile

Before proceeding, be sure you have already installed internet-in-a-box via pip 
or git (Ubuntu/Fedora) or yum repository (Fedora).

1. Install and activate mod_wsgi and mod_sendfile

    Debian/Ubuntu:
    apt-get install libapache2-mod-wsgi libapache2-mod-xsendfile
    # Enable WSGI and X-SendFile modules
    a2enmod wsgi xsendfile

    Fedora/OLPC:
    yum install mod_wsgi mod_xsendfile


2. Copy the iiab.wsgi script to /var/www (this assumes /var/www is your
document root)

    cp `which iiab.wsgi` /var/www/


3. Configure Apache for IIAB

First, find the iiabstatic directory name, so run:
python -c 'import iiab; import os; print os.path.dirname(iiab.__file__) + "/static"'

Create a new file at /etc/httpd/conf.d/iiab.conf (Fedora/OLPC)
or /etc/apache2/conf.d/iiab.conf (Ubuntu/Debian) with your favorite text editor, 
containing the following necessary information:

XSendFile on
XSendFilePath /
WSGIScriptAlias /iiab /var/www/iiab.wsgi
Alias /iiabstatic /usr/lib/python2.7/site-packages/iiab/static

The information turns on XSendFile and adds a WSGI script alias to the iiab.wsgi script.  (NOTE for Debian 6: comment out XSendFilePath if using old version of mod_xsendfile below 0.9 and you may need to add 'XSendFileAllowAbove on')
It also sets up an alias for static files from /iiabstatic to the installation directory 
of IIAB. (You may have to change your path depending on your configuration.)

IF you are using Apache 2.4 or above (Fedora 18 and OLPC OS) also add:

<Directory /usr/lib/python2.7/site-packages/iiab/static>
    Require all granted
</Directory>


Where /usr/lib/python2.7/dist-packages/iiab/static should be replaced
with the iiabstatic directory from above.

Note, if you have an existing Apache setup you will probably want to
configure these aliases in the context of a VirtualHost instead of globally
as shown.


4. Restart Apache

Debian/Ubuntu:
    /etc/init.d/apache2 restart
Fedora/OLPC:
    systemctl restart httpd

* You'll have to run this command every time you exit the current user session
and log back in.


5. Point your browser at:
    http://localhost/iiab
    
* If you haven't already, please store the Quickstart Sampler contents in /knowledge
    


Dataset Location
----------------

The IIAB dataset is stored in a directory named 'knowledge'.

By default, the IIAB software searches for its dataset 'knowledge' directory in
the root filesystem, and then in the root of every mounted disk.  It then
checks for 'knowledge' in the current working directory.  

So if you have placed the dataset in a directory named 'knowledge' on an
external USB drive, IIAB should find it by default when the drive
auto-mounts.

You can specify another location by setting 'knowledge_dir' in the 'DEFAULT'
section of the configuration file.  For example:

cat <<EOF >/etc/iiab.conf
[DEFAULT]
knowledge_dir = /mnt/data/knowledge
search_for_knowledge_dir = False
EOF


Configuration Files
-------------------

Upon startup, IIAB reads the following configuration files in order if they
exist:

    (install dir)/iiab/defaults.ini
    (install dir)/iiab/wsgi.ini (Only if run as a WSGI script)
    /etc/iiab.conf
    $(HOME)/.iiab.conf
    Any file specified with command line --config option

Directives in later files can override earlier directives.  See
iiab/defaults.ini for available options.

----