Skip to content

Latest commit

 

History

History
86 lines (67 loc) · 4.83 KB

INSTALL.md

File metadata and controls

86 lines (67 loc) · 4.83 KB

Install

TwArχiv is a Django application that interfaces with Open Humans for the file storage and user management and that is designed to be deployed to Heroku. As such there are some dependencies and intricacies that need to be taken into account. NOTE: We recommend installation on python3.

Dependencies

Database(s)

TwArχiv uses two kinds of databases for short- and long-term storage. The short term storage (for managing tasks that are not run on the webserver) is done with redis while the long-term storage is done with postgresql. If you are deploying to the heroku production environment you just have to click the appropriate add-ons.

For your development environment you have to install both redis and postgresql on your local machine. If you are running macOS and using brew (or are a user of linuxbrew) you can install both with the following commands:

brew install redis
brew install postgresql

You can then run redis-server from your command line to start an instance of redis. The configuration of postgres can be a bit more involved. Check out this blogpost for some tips.

Python modules

Django in general and TwArχiv in particular requires a larger set of python libraries. The current list can be found in the requirements.txt in this repository. Right now the requirements are the following:

gunicorn==19.7.1
pytz==2017.2
gender_guesser==0.4.0
pandas==0.20.3
tzwhere==3.0.3
Django==1.11.3
dj-database-url==0.4.2
whitenoise==3.3.1
psycopg2==2.7.3.1
redis==2.10.6
celery==4.1.0
requests==2.18.4
timezonefinder==2.1.2
geojson==2.3.0
arrow==0.12.0

If you are using heroku in your development environment it should take care of installing the modules listed in requirements.txt automatically.

Create a Project on Open Humans

We want to interface with Open Humans for our project. For this reason we need to create a research project on openhumans.org. After creating an account go to https://www.openhumans.org/direct-sharing/projects/manage/ and generate a new OAuth project. The most important parts to get right are the enrollment URL and the redirect URL. For your development environment these should be the right URLs:

enrollment: http://127.0.0.1:5000/users/
redirect: http://127.0.0.1:5000/users/complete # no trailing slash!

Start development environment

All good so far? Then we can now start developing in our local environment. I recommend using the heroku-cli interface to boot up both the celery-worker as well as the gunicorn webserver. You can install the CLI using brew install heroku/brew/heroku (or however that works on non-macs). If you are in the root directory of this repository and run heroku local:run python manage.py migrate, it will perform migrations to the database. heroku local will then use the Procfile to spawn local web & celery servers. If you've configured everything correctly you should be able to point your browser to http://127.0.0.1:5000/ and see your very own copy of TwArχiv

Heroku configuration

heroku will try to read environment variables from .env for your local environment. Make sure you have such a file. It should contain the following keys:

REDIS_URL=redis:// # where is your redis server located? most likely at this url if in dev
DATABASE_URL=postgres:///username # where does your postgres DB live?
SECRET_KEY=foobar # the Django Secret Key
ON_HEROKU=False # is our app deployed on heroku?
OH_CLIENT_ID=NOT_A_KEY_EITHER # the client ID for your Open Humans project
OH_CLIENT_SECRET=NOTAREALKEY # the secret key you get from Open Humans when creating a project.
OH_ACTIVITY_PAGE=https://www.openhumans.org/activity/your-activity-name/ # What is your Project on Open Humans?
APP_BASE_URL=http://127.0.0.1:5000/users # where is our app located? Open Humans wants to know

PYTHONUNBUFFERED=true # make sure we can print to console

This file contains private data that would allow other parties to take over your project. So make sure that you don't commit this file to your Git repository.

Deploy to heroku production

Once it's set up it is as easy as running git push heroku master. For obvious reasons (see above) it won't have the .env file for setting the environment variables. For that reason you have to manually specify them for the production environment. The heroku cli makes this easy:

heroku config:set SECRET_KEY=foobar
heroku config:set APP_BASE_URL=http://www.example.com

Important: Don't forget to set ON_HEROKU=True. Otherwise the automatic setup of your database environment will not work and you will wonder why the database migrations & queries won't work.

You don't have to set the REDIS_URL and DATABASE_URL in production. This will be done by heroku!