Installation¶
To run Signalbox you will need some kind of Unix with python 2.7 available. Ubuntu 12.04 LTS is currently recommended, but OS X is fine too for development.
To get up and running quickly, the easiest way is currently to use Heroku_ . Heroku have a free plan which is capable enough for even quite large studies, although self-hosting is also straightforward.
Prerequisites¶
For hosted installations, you just need python, and pip.
For local development, on Ubuntu 12.04, you can install everything you need for a development machine like this:
sudo apt-get install -y python-dev postgresql-server-dev-9.1 libjpeg-dev virtualenvwrapper libmagic-dev git mercurial zlib1g-dev libfreetype6 libfreetype6-dev
export WORKON_HOME=~/Envs
mkdir -p $WORKON_HOME
source /usr/local/bin/virtualenvwrapper.sh
Hosted installation on Heroku¶
To get Signalbox running on Heroku’s free plan (which is ideal for normal sized studies), you first need to:
Sign up for an account with Heroku (https://devcenter.heroku.com/articles/quickstart) and install their command line tool. You should upload your keys to the server to avoid having to repeatedly type your password:
heroku keys:add
Optionally, if you want to upload images or other media for studies or questionnaires, sign up with Amazon for an S3 storage account (uploaded image files cannot be kept on heroku; see http://aws.amazon.com).
Optionally, if you plan to send email, obtain the details (host, username, password) for an SMTP email server you will use. Amazon’s ‘simple email service’, SES, is good: http://aws.amazon.com/ses/
Optionally, if you plan on using interactive telephone calls or SMS, sign up with Twilio and make a note of your secret ID and key: https://www.twilio.com.
Installation¶
Install the heroku command line program and authenticate:
wget -qO- https://toolbelt.heroku.com/install-ubuntu.sh | sh
ssh-keygen
heroku keys:add
Clone the example project:
git clone GITHUBREPO newname
cd newname
pip install -r requirements.txt
The run the install script:
heroku_install_signalbox
At this point, your installation should be up and running on heroku:
heroku open
But you need to create the first user to login to the admin site:
heroku run app/manage.py createsuperuser
Scheduled tasks¶
Remember to add a scheduled task to send observations via the heroku control panel. The frequency is up to you - polling more often can cost more in dyno time if it overruns the free quota (but not much), but you’ll want to add scheduled tasks for these scripts:
app/manage.py send
app/manage.py remind
If adding through cron on your own server remember to make sure the python used has signalbox in it’s path (i.e. activate the virtualenv first).
Environment variables¶
Note that all settings, API keys, and passwords are stored in environment variables (see http://www.12factor.net/config).
Environment variables can be se using:
heroku config:set VAR=SOMEVALUE
The key ones you will need to set are:
AWS_STORAGE_BUCKET_NAME
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
TWILIO_ID
TWILIO_TOKEN
EMAIL_HOST
EMAIL_HOST_USER
EMAIL_HOST_PASSWORD
Others are listed below for reference.
Version control¶
Signalbox can use django_reversion to keep track of changes to Answer, Reply and Observation objects to provide an audit trail for a trial. It’s not enabled by default, but to turn it on you can set an environment variable:
heroku config:set USE_VERSIONING=1
Local install for development¶
Once you have Signalbox installed in a virtualenv and a hosted instance running, it’s easy to start hacking on it locally to update templates etc.
First make a database with postgres (for development, allow the local user all permissions).
createdb sbox
Then update the DATABASE_URL environment variable to match your new database. If everything works, open http://127.0.0.1:8000/admin to view the admin site on your development machine.
Make changes in the local repo, commit them and then:
git push heroku master
Browser compatibility¶
The front-end (participant facing pages) should work in almost all browsers, including IE7.
The admin interface works best in a recent webkit browser (Safari or Chrome) but will largely function in IE7 (although the menus are slightly broken, they are usable). Everything will work properly in IE8 onwards.
Note
It’s recommended to use Chrome-Frame if IE7 is the only available browser. See: https://developers.google.com/chrome/chrome-frame/
Warning
Check everything works in your target browsers early in the trial setup. The health services and large firms have some weird and wonderful stuff deployed.
Custom domain names¶
You can add your own domain name to the app, but you will need to update the ALLOWED_HOSTS environment variable. See https://docs.djangoproject.com/en/dev/ref/settings/#allowed-hosts and https://devcenter.heroku.com/articles/config-vars.
Reference for all user-configurable environment variables¶
Each of these is loaded from an environment variable by signalbox.configurable_settings.py, and some are documented there:
DB_URL default: postgres://localhost/sbox
LOGIN_FROM_OBSERVATION_TOKEN
SHOW_USER_CURRENT_STUDIES
DEFAULT_USER_PROFILE_FIELDS
DEBUG
AWS_STORAGE_BUCKET_NAME
COMPRESS_ENABLED
AWS_QUERYSTRING_AUTH
SECRET_KEY
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
TWILIO_ID
TWILIO_TOKEN
ALLOWED_HOSTS
SESSION_COOKIE_HTTPONLY
SECURE_BROWSER_XSS_FILTER
SECURE_CONTENT_TYPE_NOSNIFF
SECURE_SSL_REDIRECT
SESSION_COOKIE_AGE
SESSION_SAVE_EVERY_REQUEST
SESSION_EXPIRE_AT_BROWSER_CLOSE
SESSION_COOKIE_SECURE=False
USE_VERSIONING=False