Getting Started — django-open-humans documentation

# 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`.