Installation Guide

Installation Options

VIGIA can be deployed in several ways depending on your needs:

Docker Compose

Recommended for most usersEasy setup with all dependencies included

Manual Installation

Full controlInstall backend and frontend separately

Production Deployment

Enterprise readyKubernetes, load balancing, high availability

Development Setup

For contributorsLocal development environment

System Requirements

Minimum Requirements

CPU: 2 cores
RAM: 4 GB
Storage: 20 GB
OS: Linux (Ubuntu 20.04+), macOS, Windows (with WSL2)

Recommended for Production

CPU: 4+ cores
RAM: 8+ GB
Storage: 100+ GB SSD
OS: Ubuntu 22.04 LTS or RHEL 8+
Network: Static IP, HTTPS support

Software Dependencies

Docker
Manual

Docker Engine 24.0+
Docker Compose 2.20+

Docker Compose Installation (Recommended)

Install Docker

Install Docker and Docker Compose on your system:

# Update package index
sudo apt-get update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get install docker-compose-plugin

Get VIGIA Source Code

Clone or extract the VIGIA source code:

# If using git
git clone https://github.com/your-org/vigia.git
cd vigia

# Or extract from archive
unzip vigia-source.zip
cd vigia

Configure Environment

Create a .env file with your configuration:

.env

# ===== Database =====
DATABASE_URL=postgresql://postgres:postgres@db:5432/vigiadb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=SecurePassword123!
POSTGRES_DB=vigiadb

# ===== Security =====
SECRET_KEY=generate-a-secure-random-key-here-min-32-chars
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=480

# ===== CORS =====
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173,https://yourdomain.com
CORS_ALLOW_ALL=false

# ===== Default Admin =====
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_EMAIL=admin@yourdomain.com
DEFAULT_ADMIN_PASSWORD=ChangeThisPassword!

# ===== Multi-Tenant (Optional) =====
# MASTER_DATABASE_URL=postgresql://postgres:postgres@db:5432/vigia_master
# TENANT_DB_TEMPLATE=postgresql://postgres:postgres@db:5432/{db_name}

# ===== AI Features (Optional) =====
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4
GEMINI_API_KEY=your-gemini-api-key

# ===== OCR Configuration =====
OCR_LANGS=spa+eng
# POPPLER_PATH=/usr/bin  # Linux
# TESSERACT_CMD=/usr/bin/tesseract  # Linux

# ===== Email Configuration (Optional) =====
MAIL_PROVIDER=SMTP
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
SMTP_FROM_NAME=VIGIA Pharmacovigilance

# ===== VigiAccess Integration (Optional) =====
VIGIACCESS_API_BASE_URL=https://api.vigiaccess.org
VIGIACCESS_API_KEY=your-vigiaccess-key

# ===== Logging =====
LOG_LEVEL=INFO
VIGIA_SILENCE_APSCHEDULER=0
VIGIA_SILENCE_MAIL_POLLER=1

# ===== Background Jobs =====
FOLLOWUP_AUTOSEND_ENABLED=1
FOLLOWUP_AUTOSEND_INTERVAL_SEC=300
SEGUIMIENTO_ESPECIAL_AUTOSEND_ENABLED=0
SURVEILLANCE_SCHED_ENABLED=1
MAIL_POLL_ENABLED=0

Security Best Practices:

Generate a strong SECRET_KEY (min 32 characters)
Use strong passwords for database and admin user
Never commit .env to version control
Use environment-specific configurations

Review Docker Compose Configuration

The provided docker-compose.yml defines the services:

docker-compose.yml

version: "3.9"

services:
  db:
    image: postgres:15
    container_name: vigia_db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: vigiadb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d vigiadb"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: always

  api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: vigia_api
    environment:
      DATABASE_URL: postgresql+psycopg2://postgres:postgres@db:5432/vigiadb
      SECRET_KEY: devsecret
      CORS_ORIGINS: http://localhost:5173,http://127.0.0.1:5173
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8000:8000"
    restart: unless-stopped

volumes:
  pgdata:

Customize this file for production:

Add frontend service
Configure nginx reverse proxy
Add Redis for caching
Set up volume mounts for persistent storage

Build and Start Services

Launch the platform:

# Build images
docker-compose build

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f api

Expected output:

✅ Tablas listas.
✅ Tabla doc_formato creada.
▶ surv_scheduler iniciado.
▶ followup_scheduler_loop iniciado.
INFO:     Uvicorn running on http://0.0.0.0:8000

Verify Installation

Test the deployment:

# Health check
curl http://localhost:8000/health
# {"ok": true}

# API documentation
curl http://localhost:8000/docs
# Should return HTML page

# Database tables
curl http://localhost:8000/api/v1/admin/db/debug
# {"tables": ["users", "icsr", "products", ...]}

Manual Installation

For more control or development purposes, install components separately.

Backend Setup

Install Python Dependencies

cd backend

# Create virtual environment
python3.10 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install requirements
pip install -r requirements.txt

Key dependencies from requirements.txt:

fastapi[all] - Web framework
sqlalchemy - ORM
psycopg2-binary - PostgreSQL adapter
python-jose[cryptography] - JWT tokens
pytesseract - OCR
openai - AI integration
celery - Background tasks

Install System Dependencies

sudo apt-get update
sudo apt-get install -y \
  tesseract-ocr \
  tesseract-ocr-spa \
  tesseract-ocr-eng \
  poppler-utils \
  libpq-dev \
  python3-dev

Set Up PostgreSQL

# Install PostgreSQL 15
sudo apt-get install postgresql-15 postgresql-contrib

# Start service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql

CREATE DATABASE vigiadb;
CREATE USER vigia_user WITH ENCRYPTED PASSWORD 'SecurePassword123!';
GRANT ALL PRIVILEGES ON DATABASE vigiadb TO vigia_user;
\q

Update .env:

DATABASE_URL=postgresql://vigia_user:SecurePassword123!@localhost:5432/vigiadb

Initialize Database

# Run migrations (if using Alembic)
alembic upgrade head

# Or create tables directly
python -c "from app.core.database import Base, engine; Base.metadata.create_all(bind=engine)"

# Create default admin user
python create_user.py

Start Backend Server

# Development with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production with Gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -

Frontend Setup

Install Node.js Dependencies

cd frontend

# Install packages
npm install

# Or with yarn
yarn install

Key packages from package.json:

react 19.1.0 - UI library
@coreui/react 5.7.1 - UI components
react-router-dom 7.8.0 - Routing
axios 1.11.0 - HTTP client
chart.js 4.5.1 - Charts

Configure API Endpoint

Create frontend/.env:

.env

VITE_API_BASE_URL=http://localhost:8000
VITE_API_VERSION=v1

Start Development Server

# Development with hot reload
npm run dev
# Opens on http://localhost:5173

# Build for production
npm run build
# Output in dist/

# Preview production build
npm run preview

Deploy Frontend (Production)

Serve the built frontend with nginx:

/etc/nginx/sites-available/vigia

server {
    listen 80;
    server_name vigia.yourdomain.com;
    
    root /var/www/vigia/frontend/dist;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    location /api/ {
        proxy_pass http://localhost:8000/api/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable and restart nginx:

sudo ln -s /etc/nginx/sites-available/vigia /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Production Deployment

SSL/HTTPS Configuration

Install Certbot

sudo apt-get install certbot python3-certbot-nginx

Obtain SSL Certificate

sudo certbot --nginx -d vigia.yourdomain.com

Auto-Renewal

sudo certbot renew --dry-run

Systemd Service (Backend)

Create /etc/systemd/system/vigia-api.service:

[Unit]
Description=VIGIA Pharmacovigilance API
After=network.target postgresql.service

[Service]
Type=notify
User=vigia
Group=vigia
WorkingDirectory=/opt/vigia/backend
Environment="PATH=/opt/vigia/backend/venv/bin"
ExecStart=/opt/vigia/backend/venv/bin/gunicorn app.main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile /var/log/vigia/access.log \
  --error-logfile /var/log/vigia/error.log
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable vigia-api
sudo systemctl start vigia-api
sudo systemctl status vigia-api

Database Backups

#!/bin/bash
# /opt/vigia/scripts/backup.sh

BACKUP_DIR="/backup/vigia"
DATE=$(date +%Y%m%d_%H%M%S)
FILE="$BACKUP_DIR/vigiadb_$DATE.sql"

# Create backup
pg_dump -U vigia_user vigiadb > "$FILE"

# Compress
gzip "$FILE"

# Keep only last 30 days
find $BACKUP_DIR -name "vigiadb_*.sql.gz" -mtime +30 -delete

echo "Backup completed: $FILE.gz"

Add to crontab:

0 2 * * * /opt/vigia/scripts/backup.sh

Multi-Tenant Deployment

For multi-tenant setups:

Database per Tenant: Each tenant gets isolated PostgreSQL database
Subdomain Routing: tenant1.vigia.com, tenant2.vigia.com
Shared Application: Single API instance serves all tenants

# Example tenant routing in app/core/database.py
from fastapi import Request
from sqlalchemy import create_engine

def get_tenant_db(request: Request):
    host = request.headers.get("host", "")
    tenant = host.split(".")[0]  # Extract subdomain
    
    db_url = settings.TENANT_DB_TEMPLATE.format(db_name=f"vigia_{tenant}")
    engine = create_engine(db_url)
    return engine

Troubleshooting

Import Errors

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Check Python version
python --version  # Should be 3.10+

Database Connection Failed

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U vigia_user -d vigiadb

# Check DATABASE_URL format
# postgresql://user:password@host:port/database

OCR Not Working

# Verify Tesseract installation
tesseract --version
tesseract --list-langs

# Install Spanish language data
sudo apt-get install tesseract-ocr-spa

# Set paths in .env
TESSERACT_CMD=/usr/bin/tesseract
OCR_LANGS=spa+eng

Next Steps

Configuration Guide

Advanced configuration options

API Reference

Explore the REST API

User Guide

Learn platform features

Administration

Set up users and access control

Get Started

Core Features

User Guides

Modules

Regulatory

Administration

Installation Guide

Installation Options

Docker Compose

Manual Installation

Production Deployment

Development Setup

System Requirements

Minimum Requirements

Recommended for Production

Software Dependencies

Docker Compose Installation (Recommended)

Manual Installation

Backend Setup

Frontend Setup

Production Deployment

SSL/HTTPS Configuration

Systemd Service (Backend)

Database Backups

Multi-Tenant Deployment

Troubleshooting

Next Steps

Configuration Guide

API Reference

User Guide

Administration

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Modules

Regulatory

Administration

Documentation Index

​Installation Options

Docker Compose

Manual Installation

Production Deployment

Development Setup

​System Requirements

​Minimum Requirements

​Recommended for Production

​Software Dependencies

​Docker Compose Installation (Recommended)

​Manual Installation

​Backend Setup

​Frontend Setup

​Production Deployment

​SSL/HTTPS Configuration

​Systemd Service (Backend)

​Database Backups

​Multi-Tenant Deployment

​Troubleshooting

​Next Steps

Configuration Guide

API Reference

User Guide

Administration

Build docs developers (and LLMs) love

Installation Options

System Requirements

Minimum Requirements

Recommended for Production

Software Dependencies

Docker Compose Installation (Recommended)

Manual Installation

Backend Setup

Frontend Setup

Production Deployment

SSL/HTTPS Configuration

Systemd Service (Backend)

Database Backups

Multi-Tenant Deployment

Troubleshooting

Next Steps