Skip to main content

​
Overview

This guide will help you quickly set up VIGIA pharmacovigilance platform using Docker Compose. You’ll have a fully functional system running in less than 5 minutes.
Prerequisites: Docker and Docker Compose installed on your system. Install Docker →

​
Quick Setup with Docker Compose

1

Clone and Navigate to Directory

First, obtain the VIGIA source code and navigate to the project directory:
cd vigia-platform
2

Configure Environment Variables

Create a .env file in the root directory with your configuration:
.env
# Database Configuration
DATABASE_URL=postgresql://postgres:postgres@db:5432/vigiadb

# Security
SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=480

# CORS (for development)
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Default Admin User
DEFAULT_ADMIN_USERNAME=adminuser
DEFAULT_ADMIN_EMAIL=admin@local
DEFAULT_ADMIN_PASSWORD=changeme

# Optional: AI Features
OPENAI_API_KEY=sk-your-openai-key
GEMINI_API_KEY=your-gemini-key
Make sure to change the SECRET_KEY and DEFAULT_ADMIN_PASSWORD in production environments!
3

Start the Platform

Launch all services with Docker Compose:
docker-compose up -d
This will start:
  • PostgreSQL 15 database on port 5432
  • FastAPI backend on port 8000
  • Database migrations and table creation
  • Default admin user creation
docker-compose logs -f api
4

Verify Installation

Check that all services are running:
# Check API health
curl http://localhost:8000/health
# Response: {"ok": true}

# Check database connection
curl http://localhost:8000/healthz
# Response: {"status": "ok"}
5

Access the API Documentation

VIGIA includes interactive API documentation powered by FastAPI:You can test all endpoints directly from the browser!

​
First Login

Now that VIGIA is running, let’s authenticate and access the system: 
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=adminuser&password=changeme"
Save the access_token returned - you’ll need it for authenticated API requests. Include it in the Authorization: Bearer <token> header.

​
Create Your First ICSR

Let’s create a sample Individual Case Safety Report: 
import requests

# Use the token from login
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create ICSR payload
icsr_data = {
    "paciente_iniciales": "J.S.",
    "paciente_edad": 45,
    "paciente_sexo": "Masculino",
    "paciente_peso": 75.5,
    "reportante_nombre": "Dr. María González",
    "reportante_ocupacion": "Médico",
    "reportante_email": "[email protected]",
    "producto_sospechoso": "Paracetamol 500mg",
    "descripcion_evento": "Paciente presentó urticaria generalizada 2 horas después de administración",
    "fecha_inicio_evento": "2026-03-01",
    "gravedad": "leve",
    "estado": "nuevo"
}

response = requests.post(
    "http://localhost:8000/api/v1/icsr",
    headers=headers,
    json=icsr_data
)

icsr = response.json()
print(f"ICSR Created! ID: {icsr['id']}")

{
  "id": 1,
  "numero": "ICSR-2026-001",
  "paciente_iniciales": "J.S.",
  "paciente_edad": 45,
  "producto_sospechoso": "Paracetamol 500mg",
  "gravedad": "leve",
  "estado": "nuevo",
  "created_at": "2026-03-03T10:30:00Z",
  "updated_at": "2026-03-03T10:30:00Z"
}

​
Retrieve and List ICSRs

Fetch the ICSRs you’ve created: 
# Get all ICSRs (paginated)
response = requests.get(
    "http://localhost:8000/api/v1/icsr",
    headers=headers,
    params={"page": 1, "per_page": 10}
)

data = response.json()
print(f"Total ICSRs: {data['total']}")
for icsr in data['items']:
    print(f"- {icsr['numero']}: {icsr['producto_sospechoso']}")

# Get specific ICSR by ID
icsr_id = 1
response = requests.get(
    f"http://localhost:8000/api/v1/icsr/{icsr_id}",
    headers=headers
)
icsr = response.json()
print(f"ICSR Details: {icsr['descripcion_evento']}")

​
Upload and Process Document with OCR

VIGIA can extract adverse event information from documents: 
import requests
from pathlib import Path

# Upload a document for OCR processing
file_path = "adverse_event_report.pdf"

with open(file_path, "rb") as f:
    files = {"file": (Path(file_path).name, f, "application/pdf")}
    
    response = requests.post(
        "http://localhost:8000/api/v1/ocr/extract",
        headers={"Authorization": f"Bearer {token}"},
        files=files
    )

ocr_result = response.json()
print(f"Extracted Text: {ocr_result['text'][:200]}...")  # First 200 chars

# Use NLP to extract structured data
response = requests.post(
    "http://localhost:8000/api/v1/nlp/extract",
    headers=headers,
    json={"text": ocr_result["text"], "language": "es"}
)

extracted_data = response.json()
print(f"Extracted Events: {extracted_data['events']}")
OCR Requirements: For OCR functionality, ensure Tesseract and Poppler are installed:
# Ubuntu/Debian
apt-get install tesseract-ocr tesseract-ocr-spa poppler-utils

# macOS
brew install tesseract tesseract-lang poppler

​
Configure Multi-Tenant (Optional)

VIGIA supports multi-tenant architecture for managing multiple organizations: 
# app/core/config.py configuration

MASTER_DATABASE_URL = "postgresql://user:pass@localhost/vigia_master"
TENANT_DB_TEMPLATE = "postgresql://user:pass@localhost/{db_name}"

# Create tenant database
import requests

response = requests.post(
    "http://localhost:8000/api/v1/admin/clientes",
    headers=headers,
    json={
        "nombre": "Hospital Central",
        "db_name": "hospital_central",
        "subdomain": "hospital",
        "plan": "enterprise"
    }
)

tenant = response.json()
print(f"Tenant created: {tenant['subdomain']}.vigia.com")

​
Next Steps

Congratulations! You now have VIGIA running. Here’s what to explore next:

Full Installation Guide

Learn about production deployment and advanced configuration

ICSR Management

Deep dive into case management features

IPS Reports

Generate periodic safety update reports

API Reference

Complete API documentation

​
Troubleshooting

If the API can’t connect to PostgreSQL:
# Check database is running
docker-compose ps db

# View database logs
docker-compose logs db

# Verify connection string in .env
DATABASE_URL=postgresql://postgres:postgres@db:5432/vigiadb
If ports 8000 or 5432 are already in use:
docker-compose.yml
services:
  api:
    ports:
      - "8001:8000"  # Change external port
  db:
    ports:
      - "5433:5432"  # Change external port
If login fails:
  1. Check the default admin credentials in .env
  2. Ensure the database was properly initialized
  3. Check API logs: docker-compose logs api
  4. Recreate admin user:
docker-compose exec api python create_user.py

​
Common Commands

# Stop all services
docker-compose down

# Stop and remove volumes (fresh start)
docker-compose down -v

# Rebuild containers
docker-compose up -d --build

# View API logs
docker-compose logs -f api

# Access database shell
docker-compose exec db psql -U postgres -d vigiadb

# Run database migrations
docker-compose exec api alembic upgrade head
Always backup your database before running migrations or updates in production:
docker-compose exec db pg_dump -U postgres vigiadb > backup.sql

Build docs developers (and LLMs) love

Get started for freeTalk to us