Installation and Deployment

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

Install Mongodb:

Ubuntu 12.04:

  sudo apt-get install mongodb
  sudo start mongodb

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 or update your local_settings.py file first, (if used)
• (or) if you are using Structured Settings, update that environment.
• 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.

• 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 apache libapache2-mode-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:

To deploy 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]