Installation and Deployment - SEL-Columbia/formhub GitHub Wiki

Warning: This guide is obsolete and incomplete. If you want to install from source, please use the new guide instead.

Otherwise, consider using these pre-built server images instead:

The public Formhub Amazon Machine Image (AMI) to Run Your Own Formhub Instances on Amazon Web Services (AWS)
The public Formhub Virtual Disk Image (VDI) to Run Your Own Formhub Instances on VirtualBox

### Install system libraries and start services:

  sudo apt-get update
  sudo apt-get upgrade
  sudo apt-get install default-jre gcc git python-dev python-virtualenv libjpeg-dev libfreetype6-dev zlib1g-dev rabbitmq-server build-essential libxslt1-dev

Note: please use the latest version of python 2.X.

Install Mongodb:

Ubuntu 12.04:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10
echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list
sudo apt-get update
sudo apt-get install mongodb-10gen

You may need to run sudo apt-get remove mongodb-clients if you followed the old instructions and had the package mongodb package.

Ubuntu 10.04

  sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
  sudo echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' >> /etc/apt/sources.list
  sudo apt-get update
  sudo apt-get install mongodb-10gen

Set up a new virtual environment:

  mkdir ~/virtual_environments
  cd ~/virtual_environments
  virtualenv --no-site-packages formhub
  source formhub/bin/activate

Make directory structure and clone formhub:

  mkdir -p ~/src/formhub-app
  cd ~/src/formhub-app
  git clone git://github.com/modilabs/formhub.git
  cd formhub
  git submodule init
  git submodule update

Install requirements:

(NB: there is a known bug that prevents numpy from installing correctly when in requirements.pip file)

  pip install numpy  --use-mirrors
  pip install -r requirements.pip

(NB: PIL under virtualenv usually does not have some codecs compiled| to make sure jpeg codec is included)

  sudo ln -s /usr/lib/x86_64-linux-gnu/libfreetype.so /usr/lib/
  sudo ln -s /usr/lib/x86_64-linux-gnu/libz.so /usr/lib/
  sudo ln -s /usr/lib/x86_64-linux-gnu/libjpeg.so /usr/lib/
  pip install -r requirements.pip

(OPTIONAL) For MySQL, s3, ses:

  # apt-get install libmysqlclient-dev mysql-server
  pip install -r requirements-mysql.pip

NOTE: If you inted to use special characters from other languages within your forms, or are unsure if you will, you shoud ensure your databse uses the utf-8 characterset by default e.g. for mysql

  mysql> CREATE DATABASE formhub CHARACTER SET utf8;
  pip install -r requirements-s3.pip
  pip install -r requirements-ses.pip

(OPTIONAL) For PostgreSQL:

   sudo apt-get install postgresql
   sudo apt-get build-dep python-psycopg2
   pip install psycopg2

a good source of instructions for installing a postgresql server can be found at:

https://help.ubuntu.com/community/PostgreSQL

Create a database and start server:

create a Settings Preset following one of the examples in the formhub/presets folder. If you do not define a DJANGO_SETTINGS_MODULE environment variable, your preset will be formhub/presets/default_settings.py. Define your preset using a command like export DJANGO_SETTINGS_MODULE=formhub.preset.my_preset. This might best be done in your ~/.bashrc file.
(or, be old fashioned and) create or update your local_settings.py file.
and then:

  python manage.py syncdb --noinput
  python manage.py migrate

optional: create a super user

  python manage.py createsuperuser

Configure the celery daemon:

Copy the required files from the extras directory:

  sudo cp ~/src/formhub-app/formhub/extras/celeryd/etc/init.d/celeryd /etc/init.d/celeryd
  sudo cp ~/src/formhub-app/formhub/extras/celeryd/etc/default/celeryd /etc/default/celeryd

Open /etc/default/celeryd and update the path to your formhub install directory, if you directory structure is identical to what is described above, you only need to update your username, and your preset in DJANGO_SETTINGS_MODULE.
Start the celery daemon

  sudo /etc/init.d/celeryd start

Test your installation using the development server:

  python manage.py runserver

if you get an error like: "Site matching query does not exist", follow these instructions:

The Site object for your Django project is missing. Each Django project has a Site object which contains the site's name and domain. It is usually automatically created when creating a Django project (in particular, when the syncdb command runs) but in your case it seems that didn't happen.

To fix it:

Open the Django shell for your site (python manage.py shell).

Type the following:

>>> from django.contrib.sites.models import Site
>>> Site.objects.create(name='example.com', domain='example.com')

If you want to change these values later, go to your admin panel (/admin/) and edit the site object in the section Sites.

(OPTIONAL) Apache and system administration tools:

  sudo apt-get install apache2 libapache2-mod-wsgi
  sudo apt-get install htop monit

Running Tests:

To run all tests enter the following:

  python manage.py test

To run the tests for a specific app, e.g. main, enter:

  python manage.py test main

To run the test for a specific class in a specific app, e.g. the class TestFormErrors in main, enter:

  python manage.py test main.TestFormErrors

To run the test for a specific method in a specific class in a specific app, e.g. the method test_submission_deactivated in the class TestFormErrors in main, enter:

  python manage.py test main.TestFormErrors.test_submission_deactivated

To run javascript tests enter the following, NOTE that the testDir and configFile paths are relative to the js_tests/EnvJasmine directory:

  ./js_tests/EnvJasmine/bin/run_all_tests.sh --testDir=../ --configFile=../env_jasmine.conf.js

(OPTIONAL) Re-compiling the less css files

Install nodejs

  sudo apt-get install python g++ make
  mkdir ~/nodejs && cd $_
  wget -N http://nodejs.org/dist/node-latest.tar.gz
  tar xzvf node-latest.tar.gz && cd `ls -rd node-v*`
  ./configure
  sudo make install

Install recess, uglifyjs and less via npm (Node Package Manager)

  sudo npm install -g recess
  sudo npm install -g uglifyjs
  sudo npm install -g less

Compile the less files

  cd ~/src/formhub-app/formhub/main/static/bootstrap
  make

Deploying:

If you wish to deploy automatically, you will need Fabric:

  pip install fabric

You will need the appopriate .pem file in order to deploy to AWS. You will need to edit fabfile.py if you want to customize the deployments.

To deploy master to the production server:

  fab deploy:prod

To deploy master to the development server:

  fab deploy:dev

To deploy a specific branch to the development server:

  fab deploy:dev,branch=[BRANCH NAME]