Getting Started

This guide assumes you are using Django as your web framework, want to start a new project and are using pipenv to manage your dependencies.

The guide is written to work for most UNIX systems.

Installing django-open-humans

Let’s start by installing pipenv if you haven’t done so before:

pip install pipenv

Now we can install Django along with django-open-humans in a virtual environment:

mkdir our_project
cd our_project
pipenv install django
pipenv install django-open-humans
pipenv shell

This installs django and django-open-humans in our new project our_project and starts the new virtual environment. With this we start a new django project:

django-admin startproject our_project .

Setting up django-open-humans

Set up settings.py

Now that we have installed everything we can get started to add django-open-humans to the INSTALLED_APPS of our Django project:

our_project/our_project/settings.py
33
34
35
36
37
38
39
40
41
 INSTALLED_APPS = [
     'django.contrib.admin',
     'django.contrib.auth',
     'django.contrib.contenttypes',
     'django.contrib.sessions',
     'django.contrib.messages',
     'django.contrib.staticfiles',
     'openhumans'
 ]

Before we can run make and run the migrations we need to add some environment variables that django-open-humans needs to properly work. At a minimum we need to set up the OPENHUMANS_APP_BASE_URL, OPENHUMANS_CLIENT_ID and OPENHUMANS_CLIENT_SECRET. To do so we add a few lines to our settings.py:

our_project/our_project/settings.py
13
14
15
16
17
import os

OPENHUMANS_APP_BASE_URL = os.getenv('OPENHUMANS_APP_BASE_URL', 'http://localhost:5000')
OPENHUMANS_CLIENT_ID = os.getenv('OPENHUMANS_CLIENT_ID', 'your_client_id')
OPENHUMANS_CLIENT_SECRET = os.getenv('OPENHUMANS_CLIENT_SECRET', 'your_client_secret')

This code reads the OPENHUMANS_APP_BASE_URL, OPENHUMANS_CLIENT_ID and OPENHUMANS_CLIENT_SECRET from the correspondingly named environment variables you should set using e.g. export OPENHUMANS_CLIENT_SECRET='my_client_secret'.

To get your own client_id and client_secret you can head to Open Humans and make your own OAuth2 data request project.

Set up urls.py

To add django-open-humans URLs to your project, update your root urls.py configuration file (i.e. the file specified by settings.ROOT_URLCONF) as follows:

our_project/our_project/urls.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('', include('main.urls')),
    path('admin/', admin.site.urls),
]

urlpatterns += [
    path('openhumans/', include('openhumans.urls')),
]

Run database migrations

Now we can migrate our tables. Those migrations will create the User and OpenHumansMember tables for us:

./manage.py migrate

And that’s all to get the basic configuration and integration into your Django project done.

Setting up your Open Humans project

For the login with Open Humans to work you need to correctly configure the REDIRECT_URL of the OAuth2 process on Open Humans. The URL path that django-open-humans creates for redirects is

/openhumans/complete

This means if you want to develop locally and your OPENHUMANS_APP_BASE_URL is http://localhost:5000, your Redirect URL should be http://localhost:5000/openhumans/complete.

Similarly, there is a deauthorization hook that you can setup on Open Humans which will automatically inform you when people have de-authorized your application. django-open-humans accepts deauthorization requests at /openhumans/deauth.