Skip to main content

Overview

This guide covers the complete installation process for MedMitra, including development and production environments. MedMitra consists of two main components:
  • Backend: FastAPI-based Python application with AI agents
  • Frontend: Next.js 14 application with TypeScript and Tailwind CSS

System Requirements

Hardware Requirements

Development

  • 4GB RAM minimum
  • 2 CPU cores
  • 5GB free disk space

Production

  • 8GB RAM recommended
  • 4 CPU cores
  • 20GB free disk space

Software Requirements

  • Node.js: 18.x or 20.x LTS
  • Python: 3.9, 3.10, 3.11, or 3.13+
  • npm / yarn / pnpm: Latest stable version
  • pip: Python package manager (included with Python)
  • Git: For cloning the repository

Backend Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/medmitra.git
cd medmitra/backend

Step 2: Set Up Python Environment

Create and activate a virtual environment:
macOS/Linux
python3 -m venv venv
source venv/bin/activate
Windows
python -m venv venv
.\venv\Scripts\activate
Your terminal prompt should change to show (venv) when activated.

Step 3: Install Python Dependencies

pip install -r requirements.txt
The following major packages will be installed:
  • fastapi==0.115.13 - Web framework
  • uvicorn==0.34.3 - ASGI server
  • pydantic==2.11.7 - Data validation
  • python-multipart==0.0.20 - File upload support
  • langchain-core==0.3.66 - LLM framework
  • langgraph==0.4.10 - Workflow orchestration
  • langchain-groq==0.3.4 - Groq LLM integration
  • llama-cloud==0.1.29 - LlamaParse document parsing
  • groq==0.29.0 - Groq API client
  • supabase==2.16.0 - Supabase client
  • postgrest==1.1.1 - PostgreSQL REST client
  • storage3==0.12.0 - File storage
  • python-dotenv==1.0.1 - Environment variable management
  • aiofiles==24.1.0 - Async file operations
  • requests==2.32.3 - HTTP library

Step 4: Configure Environment Variables

Create a .env file in the backend/ directory:
touch .env
Add the following configuration (see Configuration for details):
backend/.env
# Supabase Configuration
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="your_service_role_key_here"

# AI Service Keys
GROQ_API_KEY="your_groq_api_key_here"
LLAMAPARSE_API_KEY="your_llamaparse_api_key_here"

# Optional: Vector Database (for future features)
# WEAVIATE_API_KEY="your_weaviate_api_key"
# WEAVIATE_REST_URL="your_weaviate_url"
Never commit the .env file to version control. It’s already included in .gitignore.

Step 5: Verify Backend Installation

Start the development server:
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
You should see output similar to:
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
Test the API:
curl http://localhost:8000/
Expected response:
{
  "message": "MedMitra Backend API is running!"
}
Visit http://localhost:8000/docs to see the interactive API documentation powered by Swagger UI.

Frontend Installation

Step 1: Navigate to Frontend Directory

cd ../frontend  # From backend directory
# or
cd medmitra/frontend  # From project root

Step 2: Install Node.js Dependencies

npm install
Installation may take 2-5 minutes depending on your internet connection.
The following major packages will be installed:
  • @supabase/supabase-js@latest - Supabase client
  • @supabase/ssr@latest - Server-side rendering support

Step 3: Configure Environment Variables

Create a .env.local file in the frontend/ directory:
touch .env.local
Add the following configuration:
frontend/.env.local
# Supabase Configuration (Client-side)
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your_supabase_anon_key_here"

# Backend API URL
NEXT_PUBLIC_FASTAPI_BACKEND_URL="http://localhost:8000"

# Gladia Speech-to-Text API
NEXT_PUBLIC_GLADIA_API_KEY="your_gladia_api_key_here"
In production, update NEXT_PUBLIC_FASTAPI_BACKEND_URL to your deployed backend URL.

Step 4: Verify Frontend Installation

Start the development server:
npm run dev
You should see:
 Next.js 15.x
  - Local:        http://localhost:3000
  - Experiments:  turbopack

 Starting...
 Ready in 1.5s
The frontend uses Turbopack for ultra-fast development builds and hot module replacement.
Open http://localhost:3000 in your browser to see the MedMitra login page.

Database Setup

MedMitra uses Supabase (PostgreSQL) for data storage. You need to create the required database schema.

Step 1: Create Supabase Project

  1. Visit supabase.com and sign in
  2. Click “New Project”
  3. Choose a project name, database password, and region
  4. Wait for the project to be provisioned (1-2 minutes)

Step 2: Get API Credentials

1

Navigate to Project Settings

In your Supabase dashboard, go to SettingsAPI
2

Copy Project URL

Copy the Project URL (e.g., https://xyz.supabase.co)
3

Copy API Keys

Copy both:
  • anon public key (for frontend)
  • service_role key (for backend)
Keep the service_role key secret! It bypasses Row Level Security.

Step 3: Create Database Tables

Go to SQL Editor in your Supabase dashboard and run the following:
CREATE TABLE cases (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL,
  patient_name TEXT NOT NULL,
  patient_age INTEGER NOT NULL CHECK (patient_age > 0 AND patient_age < 150),
  patient_gender TEXT NOT NULL,
  case_summary TEXT,
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create index for faster queries
CREATE INDEX idx_cases_user_id ON cases(user_id);
CREATE INDEX idx_cases_status ON cases(status);
CREATE INDEX idx_cases_created_at ON cases(created_at DESC);

Step 4: Configure Storage Buckets

MedMitra uses Supabase Storage for file uploads:
1

Navigate to Storage

In Supabase dashboard, go to StorageBuckets
2

Create Buckets

Create two public buckets:
  • medical-documents (for lab reports and radiology images)
  • avatars (optional, for user profile pictures)
Make sure to enable “Public bucket” if you want direct URL access to files.
3

Configure Bucket Policies

Set appropriate storage policies for file upload/download permissions.

Obtaining API Keys

MedMitra requires several third-party API keys:

Groq API Key

1

Sign Up

Visit console.groq.com and create an account
2

Generate Key

Go to API Keys section and click Create API Key
3

Copy Key

Copy the generated key and add it to your .env file
Groq provides free tier access to Llama 3.3 models with generous rate limits.

LlamaParse API Key

1

Sign Up

Visit cloud.llamaindex.ai and create an account
2

Navigate to API Keys

Go to your account settings and find the API Keys section
3

Generate Key

Create a new API key for LlamaParse

Gladia API Key

1

Sign Up

Visit gladia.io and create an account
2

Access Dashboard

Navigate to your dashboard after email verification
3

Generate Key

Find the API Keys section and generate a new key
Gladia is used for speech-to-text transcription in the frontend for doctor’s notes.

Running in Production

Backend Deployment

For production deployment, use a production-grade ASGI server configuration:
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
The backend can be deployed to:

Frontend Deployment

Build the production bundle:
npm run build
npm run start
The frontend can be deployed to:

Docker Installation (Optional)

For containerized deployment, Docker configurations can be added:
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Verification Checklist

After installation, verify everything is working:
1

Backend Health

  • Backend starts without errors
  • API documentation accessible at /docs
  • Root endpoint returns success message
  • Environment variables loaded correctly
2

Frontend Health

  • Frontend starts without errors
  • Login page displays correctly
  • Dark/light mode toggle works
  • No console errors in browser
3

Database Connection

  • Supabase tables created successfully
  • Storage buckets configured
  • Authentication works (sign up/login)
4

API Integration

  • Groq API key valid
  • LlamaParse API key valid
  • Gladia API key valid (optional)
  • Backend can connect to Supabase

Next Steps

Configuration Guide

Learn about all available configuration options

Create Your First Case

Step-by-step guide to creating and analyzing cases

API Reference

Explore the complete API documentation

AI Agents

Understand MedMitra’s AI workflow

Troubleshooting

If you see ModuleNotFoundError when starting the backend:
  1. Verify virtual environment is activated: which python should show the venv path
  2. Reinstall dependencies: pip install -r requirements.txt
  3. Check Python version: python --version (should be 3.9+)
If port 8000 or 3000 is already in use:Backend:
# Find process using port 8000
lsof -i :8000
# Kill the process
kill -9 <PID>
# Or use a different port
uvicorn app:app --port 8001
Frontend:
# Next.js will automatically try port 3001 if 3000 is busy
# Or specify a port:
PORT=3001 npm run dev
If you can’t connect to Supabase:
  1. Verify URL format: should be https://xyz.supabase.co
  2. Check API keys have no extra spaces or quotes
  3. Ensure project is not paused (free tier auto-pauses after 1 week)
  4. Test connection in Supabase SQL Editor first
If npm install fails:
  1. Clear npm cache: npm cache clean --force
  2. Delete node_modules and package-lock.json: rm -rf node_modules package-lock.json
  3. Update npm: npm install -g npm@latest
  4. Try using yarn or pnpm instead

Build docs developers (and LLMs) love