Development Setup

Clone the Repository

To get started, you’ll first need to clone the GitHub repository so you can work on the project locally. In a terminal, run:

git clone git@github.com:theirc/serviceinfo.git
cd serviceinfo/

Frontend Setup

The frontend runs separately from the backend.

The Javascript dependencies are installed by Node’s NPM, both for build tools and frontend modules. Javascript libraries for the frontend app are installed from NPM and then packaged for the browser by Browserify. You’ll need to install Node, which includes npm, in order to build the frontend application if you’d like to run it.

On Mac, you can install Node with brew:

brew install node

On Ubuntu and other Linux distributions, you should download and build the latest version of Node v0.10.*. (Newer versions might not work.)

Standard package managers rarely have the most recent versions of Node that include NPM. You can download it from http://nodejs.org/download/ and follow the standard build instructions:

wget https://nodejs.org/download/release/latest-v0.10.x/node-v0.10.40.tar.gz
tar -zxf node-v0.10.40.tar.gz
cd node-v0.10.40/
./configure
make
sudo make install
cd ..

WARNING: Do not build node while your ServiceInfo virtualenv is active. Node expects Python 2.7 and our virtualenv uses Python 3.

With Node installed, you can install all frontend dependencies with npm:

npm install

Backend Setup

Below you will find basic setup instructions for the project. To begin you should have the following applications installed on your local development system:

The deployment uses SSH with agent forwarding so you’ll need to enable agent forwarding if it is not already by adding ForwardAgent yes to your SSH config.

Getting Started

If you need Python 3 installed on Ubuntu, you can use this PPA:

sudo add-apt-repository ppa:fkrull/deadsnakes
sudo apt-get update
sudo apt-get install python3-dev

To setup your local environment you should create a virtualenv and install the necessary requirements:

mkvirtualenv --python=<path>/python3 serviceinfo
pip install -U pip
pip install -U -r requirements/dev.txt

In order to use JavaScript tools that npm installs, you’ll need to add node_modules/.bin to the front of your PATH. One way to do that is to add this to your virtualenvs’ postactivate script:

if [ -d node_modules/.bin ] ; then
    if printenv PATH | grep --quiet node_modules/.bin ; then
        echo "node_modules already on PATH: $PATH"
    else
        echo "Adding node_modules to PATH"
        PATH=$(pwd)/node_modules/.bin:$PATH
    fi
fi

Install the needed Javascript tools and libraries:

npm install

Then create a local settings file and set your DJANGO_SETTINGS_MODULE to use it and also to use the javascript tools just installed:

cp service_info/settings/local.example.py service_info/settings/local.py
echo "export DJANGO_SETTINGS_MODULE=service_info.settings.local" >> $VIRTUAL_ENV/bin/postactivate
echo "unset DJANGO_SETTINGS_MODULE" >> $VIRTUAL_ENV/bin/postdeactivate
echo "PATH=$PWD/node_modules/.bin:\$PATH" >> $VIRTUAL_ENV/bin/postactivate

Exit the virtualenv and reactivate it to activate the settings just changed:

deactivate
workon serviceinfo

Now you can run the tests:

./run_tests.sh

Enabling the search engine

Running Elasticsearch can be as simple as unpacking it and then:

cd elasticsearch-1.7.4 && bin/elasticsearch

(This requires Java.)

You should add this to the bottom of config/elasticsearch.yml to limit it to a simple single-node configuration which only services the local machine:

network.host: 127.0.0.1
node.local: true
discovery.zen.ping.multicast.enabled: false

If you have less than 10% disk space free, you’ll need to make more space available or add this to the bottom of config/elasticsearch.yml:

cluster.routing.allocation.disk.threshold_enabled: false

Use the Django management commands rebuild_index, clear_index, or update_index to maintain the search index. (The index will be updated in real time after some types of changes.)

Disabling search indexing

Add this to local.py:

HAYSTACK_SIGNAL_PROCESSOR = 'haystack.signals.BaseSignalProcessor'

Running locally

Create the Postgres database and run the initial migrate:

createdb -E UTF-8 service_info
psql service_info -c "CREATE EXTENSION postgis;"
python manage.py migrate

You should now be able to build the frontend and run the development API server:

gulp

Follow the instructions for CMS configuration in the CMS setup document or just run the create_minimal_cms management command.

Now visit http://localhost:4005/ in your browser.

If you need to debug the Javascript, you might prefer to skip running Closure. You can skip closure by adding the --fast option to gulp:

gulp --fast

Celery

Use this to run a single worker with the “beat” task scheduler:

celery -B -A service_info worker -l debug

Using the staging or production database and media locally

Changes relating to the CMS, such as those affecting page templates and styles or CMS plugins, should be tested locally with the staging and/or production databases and media in order to check how the existing content will be affected. The procedure uses commands in both the ServiceInfo and ServiceInfo-ircdeploy repositories:

$ cd ServiceInfo-ircdeploy
$ workon virtualenv-with-fab
$ fab production reset_local_db
$ fab production reset_local_media:../ServiceInfo
$ cd ../ServiceInfo
$ workon virtualenv-for-ServiceInfo
$ ./manage.py migrate
$ ./manage.py change_cms_site --from=serviceinfo.rescue.org --to=localhost:8000
# If using search locally
$ ./manage.py rebuild_index --noinput