Developer Setup

This guide provides a comprehensive walkthrough for setting up your development environment to work with the JupyterHealth Exchange project. It covers configuring your Python environment, setting up a PostgreSQL database, and initializing authentication.

Step by Step¶

1. Set up your Python environment. This project uses Django version 5.2 which requires python 3.10, 3.11, 3.12 or 3.13.
2. Create a new Postgres DB. Currently only Postgres is supported because of json functions.
3. Seed the DB by running the SQL commands found in db/seed.sql.
4. Make a copy of env_example.txt, update the DB_* properties to match the new DB and save it as .env.
5. Ensure the .env is loaded into your Python environment. For example, for pipenv:

   pipenv shell

6. Start the server.

   python manage.py runserver

7. Browse to http://localhost:8000/admin and enter the credentials super@example.com Jhe1234!.
8. Browse to Applications under Django OAuth Toolkit and create a new application
   • Leave User empty
   • Set Redirect URLs to include http://localhost:8000/auth/callback and any other hosts
   • Set Type to Public
   • Set Authorization Grant Type to Authorization code
   • Leave Secret blank
   • Name the app whatever you like
   • Check Skip authorization
   • Set Algorithm to RSA with SHA-2 256
   • Skip Allowed origins
9. Create an RS256 private key.

   openssl genrsa -out oidc.key 4096

10. Create a new static PKCE code verifier - a random alphanumeric string 44 chars long.

    import random
    import string
    
    
    def generate_pkce_verifier(length=44):
        characters = string.ascii_letters + string.digits
        return "".join(random.choices(characters, k=length))
    
    
    print(generate_pkce_verifier())

11. Use the PKCE verifier to generate the PKCE code challenge.
12. Return to the .env file
    • Update OIDC_CLIENT_ID with the newly created app Client ID
    • Update the OIDC_RSA_PRIVATE_KEY with the newly created Private Key
    • Update PATIENT_AUTHORIZATION_CODE_CHALLENGE and PATIENT_AUTHORIZATION_CODE_VERIFIER with PKCE static values generated above
    • Restart the python environment and Django server
13. Browse to http://localhost:8000/ and log in with the credentials anna@example.com Jhe1234!and you should be directed to the /portal/organizations path with some example Organizations is the dropdown.

Troubleshooting¶

Issue: Blank Screen After Login on Windows¶

Symptom¶

After logging in on Windows, users are redirected to the portal, but a blank screen persists. This issue seems related to the oidc-client-ts library but is actually due to incorrectly set environment variables on Windows.

Cause¶

On Windows systems (particularly when running Django via Visual Studio Code or Git Bash), the environment variables related to OIDC in settings.py may become incorrectly formatted. This causes URLs to be malformed, preventing proper authentication.

Examples of Incorrectly Set Values¶

• OIDC_CLIENT_REDIRECT_URI: http://localhost:8000C:/Program Files/Git/auth/callback
• OIDC_CLIENT_AUTHORITY: http://localhost:8000O://

Solution¶

The solution is to explicitly hardcode the correct values to OIDC variables in your settings.py. This will prevent incorrect path injections and ensure proper URL formation, resolving the blank screen issue after login on Windows machines.

OIDC_CLIENT_REDIRECT_URI = "http://localhost:8000/auth/callback"
OIDC_CLIENT_AUTHORITY = "http://localhost:8000/o/"