SetupBooster

Installation Guide

This guide will install a locally running instance of SetupBooster on a Linux virtual machine. Ubuntu is recommended to minimize dependency issues. It is modified from the original Makahiki guide.

System Requirements

This guide is written for Ubuntu Linux 12.04.1 LTS or higher. Other distros may work, but the installation commands will be different, and not all dependencies may be available.
  • Virtual Machine (development):
    • At least 10 GB disk space
    • At least 4 GB RAM (2 GB works but is not recommended)
  • Hardware (development):
    • Dual-core CPU
    • At least 10 GB disk space
    • At least 4 GB RAM
  • Hardware (production):
    • Dual-core CPU
    • At least 10 GB disk space
    • At least 8 GB RAM

Python

Install Python 2.7.3 or higher. Do not install any version of Python 3: it is not compatible with some features of the system. Check your current installed version at the terminal: 

% python  --version
Python 2.7.3
If you don't have Python in Linux, install Python from the terminal as follows: 
% sudo apt-get install python2.7

C Compiler

SetupBooster requires a C compiler to build some of its dependency modules, such as PIL. Most Linux distributions come with the gcc compiler already installed. Check that gcc is installed: 

% gcc --version
If gcc is not installed, follow the Ubuntu documentation to install it.

Git

Git is a distributed version control system that is needed to retrieve the project files from Github. Check that it is installed: 

% git --version
If it is not installed, install it from the terminal: 
% sudo apt-get install git
If you have a Github account, you can link it to the Github installation by following Github's guide.

Pip

Pip is a tool for installing Python packages. Install it as follows: 
% sudo easy_install pip
If this does not work, try installing setuptools first: 
% sudo apt-get install python-setuptools
After you install pip, check that the installation succeeded: 
% pip --version

Virtual Environment Wrapper

Virtualenvwrapper is used to install libraries outside the global Python path. Complete the virtualenvwrapper installation guide and follow it to the end of the Quick Start section. This will install virtualenv and virtualenvwrapper. After this, create a virtual environment for setupbooster. At this point in development, the application still uses the original Makahiki virtual environment settings: 

% mkvirtualenv makahiki
Now check that the virtual environment wrapper is installed: 
% workon makahiki

Python Imaging Library

Issue the following commands in the Linux terminal to install the Python Imaging Library (PIL): 

% sudo apt-get install -y python-imaging python-dev libjpeg-dev
Check the /usr/lib directory for libjpeg (JPG) and zlib (PNG). If they are not there, you may need to make symbolic links. On a 32-bit Linux system, this would be done with these commands: 
% sudo ln -s /usr/lib/i386-linux-gnu/libjpeg.so /usr/lib/
% sudo ln -s /usr/lib/i386-linux-gnu/libz.so /usr/lib/

PostgreSQL

PostgreSQL is the backend database for SetupBooster; it was tested with 9.1.3, but any 9.1.* version should be compatible. Use this command to install it: 

% sudo apt-get install postgresql-9.1
To get the PostgreSQL server working for development use, you will need to make the postgres user "trusted" so that local processes like SetupBooster's Makahiki-based services can connect to the database via the postgres user without needing authentication. In /etc/postgresql/9.1/main, open pg_hba.conf in a text editor. Change the line 
local all postgres ident
or 
local all postgres peer
to 
local all postgres trust
and restart the database server with 
% sudo /etc/init.d/postgresql restart
You will also need to install the libpq-dev package: 
% sudo apt-get install libpq-dev
Check that postgresql has been successfully configured. If done correctly, the command 
% psql -U postgres
should not prompt you for a password.

Memcached

Memcached can improve the performance of SetupBooster in a production environment. Install its components in Ubuntu with these commands: 

% sudo apt-get install memcached
% sudo apt-get install libmemcached-dev

Download Source Code

Download the source code by cloning or forking the ICS691-Setupbooster repository: 

% git clone git://github.com/jtakayama/ics691-setupbooster.git

Initialize Virtual Environment

Switch to the ics691-setupbooster/ directory (assuming you activated this virtual environment previously in this tutorial). Then do this: 

% cd ics691-setupbooster/
% workon makahiki
This must be done each time you work on the project in a new shell.

Install Requirements

Install all of SetupBooster's other dependencies: 

% pip install -r requirements.txt
This will product a lot of output text. Psycopg2 may fail to compile the first time: 
gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -DPSYCOPG_DEFAULT_PYDATETIME=1 -DPSYCOPG_VERSION="2.4.6 (dt dec pq3 ext)" -DPG_VERSION_HEX=0x090108 -DPSYCOPG_EXTENSIONS=1 -DPSYCOPG_NEW_BOOLEAN=1 -DHAVE_PQFREEMEM=1 -I/usr/include/python2.7 -I. -I/usr/include/postgresql -I/usr/include/postgresql/9.1/server -c psycopg/psycopgmodule.c -o build/temp.linux-i686-2.7/psycopg/psycopgmodule.o -Wdeclaration-after-statement
 
In file included from psycopg/psycopgmodule.c:27:0:
 
./psycopg/psycopg.h:30:20: fatal error: Python.h: No such file or directory
 
compilation terminated.
 
error: command 'gcc' failed with exit status 1
If this happens, install python-dev and then try again. 
% sudo apt-get install python-dev

Environment Variables

SetupBooster requires that the environment variables MAKAHIKI_DATABASE_URL and MAKAHIKI_ADMIN_INFO be set. The syntax for each variable, followed by an example, is reproduced below: 

% # Syntax: postgres://<db_user>:<db_password>@<db_host>:<db_port>/<db_name>
% export MAKAHIKI_DATABASE_URL=postgres://makahiki:makahiki@localhost:5432/makahiki

% # Syntax:  <admin_name>:<admin_password>
% export MAKAHIKI_ADMIN_INFO=admin:admin
In order to load these every time the virtual environment is loaded, edit the postactivate file in $WORKON_HOME/makahiki/bin and add the variables to it. Publicly accessible servers should use a stronger password than "admin."

Initialize SetupBooster

To initialize the SetupBooster database, switch to the ics691-setupbooster/makahiki directory and run the initialize_instance.py script: 

% scripts/initialize_instance.py --type setupbooster
This command erases all modifications made to the database, including any changes made to application settings. It should not be used on a production system more than once.

Start the Server

SetupBooster comes with two servers. gunicorn is more suited for production use, while runserver is better for development use.

gunicorn:
% ./manage.py run_gunicorn
runserver:
% ./manage.py runserver

Verify Server is Running

View full size
Above: The current landing page.

Go to 127.0.0.1:8000 in a browser. You should be taken to a landing page. The password you set for the admin account as an environment variable can be used to log in. All other accounts will need to be given passwords manually, even if they were initialized by initialize_instance.py.

Configure SetupBooster

See the User Guide.

Update a Running Instance

It is possible to update a running SetupBooster instance without re-initializing the database:

  1. In the shell that is running the server, type Ctrl+C to stop the server.
  2. Switch to the ics691-setupbooter/makahiki directory and initialize the virtual environment: 
    % cd makahiki
% workon makahiki
  3. Pull the latest source code from the Setupbooster repository: 
    % git pull origin master
  4. Run the update_instance script: 
    % ./scripts/update_instance.py
  5. Start gunicorn or runserver as shown previously.