Skip to content

quick-start.md

Latest commit

 

History

History
269 lines (188 loc) · 7.63 KB

quick-start.md

File metadata and controls

269 lines (188 loc) · 7.63 KB
Raw

Quick Start Guide (Development Setup)

This guide walks you through setting up a local AugMed instance for development or testing. You will have a running API server, a connected database, and a test user able to review cases.

!!! tip "Just want to try AugMed?" If you don't need a development environment, use the One-Click Deploy (Railway, ~5 minutes) or Self-Hosted Deploy (Docker Compose, ~10 minutes) instead. This guide is for developers who want to run the services outside of Docker.

Prerequisites

Before you begin, install the following:

  • Docker Desktop (version 4.x or later) — docker.com/products/docker-desktop
  • Python 3.11 — via brew install python@3.11 (macOS) or your system package manager
  • Pipenv — pip install pipenv
  • Node.js 18+ and npm — for the frontend (if running the full stack)
  • Git

Verify your installations:

python3 --version    # Should show 3.11.x
docker --version     # Should show 4.x or later
pipenv --version

Step 1: Clone the Repositories

Clone the backend API:

git clone https://github.com/DHEPLab/augmed-api-v2.git
cd augmed-api-v2

If you also want the frontend:

git clone https://github.com/DHEPLab/augmed-app-v2.git

Step 2: Configure Environment Variables

In the augmed-api-v2 directory, create a .env file. Use the provided .env_example as a template:

cp .env_example .env

Edit .env with your local settings:

# Database connection
DATABASE_URL=postgresql://augmed:augmed@localhost:5432/augmed
POSTGRES_USER=augmed
POSTGRES_PASSWORD=augmed
POSTGRES_DB=augmed

# JWT security — change this to a random secret in any non-local environment
JWT_SECRET_KEY=your-local-secret-key-change-me

# Token expiry (in seconds); defaults to 3 days if not set
JWT_ACCESS_TOKEN_EXPIRES=259200
JWT_REFRESH_TOKEN_EXPIRES=259200

# API key for the export/RL service endpoint (service-to-service auth)
EXPORT_API_KEY=your-export-api-key

!!! note Never commit .env files to version control. The .gitignore should already exclude them.

Step 3: Start the Database

Docker Compose starts a local PostgreSQL instance:

docker-compose up -d

Verify the container is running:

docker ps
# Should show postgres_container with status "Up"

Step 4: Install Python Dependencies

pipenv install

Activate the virtual environment:

pipenv shell

Step 5: Set the Python Path

From the project root directory:

export PYTHONPATH=$(pwd)

!!! note You need to run this command each time you open a new terminal session, or add it to your shell profile.

Step 6: Start the API Server

flask run

The API will start at http://localhost:5000. Database migrations run automatically on startup.

If port 5000 is in use, run on a different port:

flask run --host=127.0.0.1 --port=5001

Verify the server is running:

curl http://localhost:5000/api/healthcheck
# Expected: {"message": "Service is up and running.", "status": "OK"}

Step 7: Start the Frontend (Optional)

If you cloned the frontend repository:

cd augmed-app-v2
npm install
npm start

The frontend will start at http://localhost:3000. It expects the API at http://localhost:5000.

!!! note If you see CORS errors in the browser console, you may need to enable CORS in the API. See the comment in src/__init__.py — uncomment the CORS lines and reinstall flask-cors with pipenv install flask-cors.

Step 8: Load Sample Data

Before participants can review cases, you need clinical data in the database. You have two options:

Option A: Seed Demo Data (Recommended for Quick Start)

Run the demo seed script to create synthetic cases, users, and configurations:

export PYTHONPATH=$(pwd)
pipenv run python -m script.seed.seed_demo

This creates 3 synthetic cases, 2 demo users (admin and researcher), and all necessary configuration. You can skip Steps 9-11 and log in immediately with researcher@demo.augmed.org / augmed-demo.

Option B: Load OMOP CSV Data

For real (de-identified) clinical data, the script/sample_data/ directory contains CSV templates in OMOP format:

script/sample_data/
├── person.csv
├── visit_occurrence.csv
├── observation.csv
├── measurement.csv
├── drug_exposure.csv
└── procedure_occurrence.csv

Load the data using the SQL load scripts in script/. You will also need to set up a page_config in the system_config table and upload an answer config via the admin API. See Creating Experiments for the full workflow.

Step 9: Create Test Users

Use the admin API to create participant accounts. Newly created users are inactive by default and cannot log in until activated.

Create a test user:

curl -X POST http://localhost:5000/admin/users \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "name": "Test Participant",
        "email": "testparticipant@example.com",
        "position": "Physician",
        "employer": "Test Hospital",
        "area_of_clinical_ex": "Internal Medicine"
      }
    ]
  }'

Expected response:

{
  "data": {"testparticipant@example.com": "added"},
  "status": "success"
}

Step 10: Upload a Display Config

The display config assigns cases to participants and specifies which clinical features they see. Create a minimal CSV file named test_config.csv:

User,Case No.,Path,Collapse,Highlight,Top
testparticipant@example.com,1,BACKGROUND.Medical History.Hypertension: Yes,FALSE,TRUE,
testparticipant@example.com,1,BACKGROUND.Family History.Cancer: No,FALSE,TRUE,

!!! note To also show the AI prediction, add a RISK ASSESSMENT.* row matching your page config. See Config CSV Format.

Upload it:

curl -X POST http://localhost:5000/admin/config/upload \
  -F "file=@test_config.csv"

Expected response:

{
  "data": [{"user_case_key": "testparticipant@example.com-1", "status": "added"}],
  "status": "success"
}

!!! note Uploading a new config replaces all existing display configs. See Config CSV Format for details.

Step 11: Activate a User and Review a Case

Users must be activated before they can log in. Currently, activation is done by directly updating the database. In a future release, this will be available through the admin API.

Activate the test user directly in the database:

docker exec -it postgres_container psql -U augmed -d augmed \
  -c "UPDATE \"user\" SET active = true, password = 'temp' WHERE email = 'testparticipant@example.com';"

!!! note Setting a real password requires going through the POST /api/auth/reset-password-request flow. For local testing, you can also set a hashed password directly. See Managing Participants for the full activation workflow.

Log in:

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "testparticipant@example.com", "password": "temp"}'

The JWT token is returned in the Authorization response header.

What's Next