Get Started

Welcome to the OHDSI GIS Working Group! This page helps you get started whether you’re deploying the Gaia toolchain, joining the working group, or proposing a use case.

Prerequisites: Docker Engine 20.10+, Docker Compose 2.0+, 8GB+ RAM, 50GB+ disk


Quick Start: Deploy Gaia

The fastest way to deploy the Gaia toolchain is using gaiaDocker from the command line (terminal/bash on mac/linux or powershell on windows):

# Clone gaiaDocker repository
git clone https://github.com/OHDSI/gaiaDocker.git
git clone https://github.com/OHDSI/gaiaCatalog.git
cd gaiaDocker

create blank secrets (only do this once)

The Gaia toolchain leverages Docker secrets to enable data retrieval from datasources that require authentication. For the quickstart we recommend running the script in the gaiaDocker root directory to create empty secrets, and then see the Gaia secrets documentation for instructions to create the secrets for the sources you will use.

mac/linux

bash ./create_secrets.sh

windows

./create_secrets.ps1 # windows

start the full Gaia stack

# Start the full Gaia stack
docker compose --profile gaia up -d

On the first start it may take several minutes to pull the containers from the docker hub container repository. NOTE: there are several profiles available (see Profiles).

verify services are running

# Verify services are running
docker compose ps

What’s deployed: - gaia-db: PostgreSQL/PostGIS (core data repository)
- gaia-core: RStudio with HADES and the gaiaCore R package (http://localhost:8787)
- gaia-postgrest: optional PostgREST API (exposes gaiaDb functions)
- gaia-catalog: Data source discovery interface
- gaia-solr: Search engine for catalog

testing

You can test various endpoints from the command line

# connect to the gaia-db database ...
# result: you will enter into a psql command line environment
docker compose exec gaia-db psql -U postgres -d gaiacore 

# test the postgrest API ...
# result: you will see a long sumamry of available funcitonality
curl http://localhost:3000/

You can also use a web browser to navigate to:

  • http://localhost:5001: the catalog discovery application
  • https://ohdsi.github.io/gaiaCatalog/browser: an alternative catalog browser

From the main pages of either browser you can view descriptive entries for datasets available in the catalog.

See Deployment Strategies for alternative deployment options (Podman, Ansible, manual, Kubernetes).


Join the Working Group

Get Connected

  1. Sign up for OHDSI Teams

  2. Join the GIS Working Group

  3. Attend Weekly Meetings

    • When: Thursdays 10 AM US Eastern
    • Where: MS Teams
    • Format: Intros (5 min) → GitHub ticket review (10-15 min) → Standup updates (2 min each) → Discussion (25-30 min) → Action items (5 min)

  4. Introduce Yourself

    • Share your interests, background, and what you hope to work on
    • Ask questions - all skill levels welcome!

Start Contributing

For Developers: - Review Developer Resources - Check Package Status - Pick a good first issue from the Project Board - Read Contributing Guidelines - Set up your development environment using Deployment Guide

For Researchers: - Propose a Use Case (see below) - Review existing use cases - Join subgroup meetings for specific projects

For Everyone: - Join discussions on Teams GIS channel - Help improve documentation - Answer questions on OHDSI Forums - Attend presentations at meetings


Propose a Use Case

Development in the OHDSI GIS Working Group is use-case driven - specific research needs determine development objectives.

Submit a Use Case

Create a Use Case Issue describing:

1. Project Deliverable - What evidence do you want to generate from combined place-related data and EHR data? - Provide enough detail for everyone to understand the final product

2. Infrastructure Needs - What changes to OHDSI GIS infrastructure/tooling are needed? - How much relies on existing vs. new infrastructure? - How much can you/your team contribute to development?

3. Timeline - Hard or soft deadlines for deliverable - Can development start immediately or must wait? - Desired cadence of development/progress meetings

4. Credit & Authorship - How should credit be attributed? - How should collaborative effort be recognized?

5. Support Needed - Help using existing tools? - Planning a development sprint? - Integrating new features?

6. Datasets - Datasets needed that are NOT already in gaiaCatalog? - Include source specifics: version, URLs, format

Use Case Workflow

  1. Submit - Create use case issue with above details
  2. Review - Working group leaders review and schedule discussion
  3. Present - Present use case at Thursday meeting
  4. Decompose - Break into specific work orders/tasks
  5. Prioritize - Add to project board, assign priority
  6. Execute - Development sprint with progress updates
  7. Deliver - Complete deliverable, share results

Use cases are tracked on the GIS Project Board and linked to specific work orders.


Project Management

GitHub Project Board

All work is tracked on the GIS Project Board:

  • Status View: Backlog → To Do → In Progress → Blocked → Review → Done
  • Use Case View: Tasks grouped by research use case
  • Priority View: High, Medium, Low priority items

Issue Types

  • Use Cases (Use Case label): Research-driven proposals
  • Work Orders (task label): Specific development tasks
  • Bugs (bug label): Software defects
  • Enhancements (enhancement label): Feature requests
  • Documentation (documentation label): Documentation updates

Weekly Meetings

Agenda (60 minutes): 1. Intros & New Members (5 min) 2. GitHub Ticket Review (10-15 min) - Review sprint tasks, update board, identify blockers 3. Standup Updates (2 min max per person) - Completed work, current work, blockers 4. Discussion Topics (25-30 min) - Technical decisions, use cases, architecture 5. Action Items & Next Steps (5 min)

See Project Management for complete process details.


Resources

Documentation

Repositories

Getting Help

Questions?

Technical Support

New to GIS/OMOP/OHDSI?

Welcome! We support all skill levels: - Pair with experienced contributors - Start with documentation tasks - Ask questions freely during meetings - Join subgroup meetings for hands-on learning - Review the OHDSI Community resources


Contact