Installation Guide

12 min read Updated Feb 6, 2026

This guide covers two installation methods for the Vantrexia RPM platform: the recommended Docker Compose approach for quick setup, and a native development setup using Python virtualenv and npm for developers who prefer direct access to the runtime environment.

Which method should I use?

Docker Compose is recommended for most users — it handles all dependencies automatically and mirrors the production environment. Choose the native development setup if you need faster hot-reload, direct debugger attachment, or prefer working without containers.

Method 1: Docker Compose (Recommended)

Docker Compose orchestrates all services — backend, frontend, database, cache, and task workers — in isolated containers with a single command.

Prerequisites

Tool Minimum Version Installation
Docker Engine 20.10+ docs.docker.com/get-docker
Docker Compose 2.0+ Included with Docker Desktop
Git 2.30+ git-scm.com/downloads

Clone & Configure

Terminal 
# Clone the repository
git clone https://github.com/highlandpc/Vantrexia.git
cd Vantrexia

# Copy environment file
cp .env.example .env

Edit .env to set at minimum the SECRET_KEY. For local development, all other defaults work out of the box. See the Configuration Guide for a full variable reference.

Start the Stack

Terminal 
# Build and start all services in detached mode
docker compose up -d --build

# Watch the logs (optional)
docker compose logs -f

Docker Compose starts the following services based on docker-compose.yml:

  • backend — Django REST API on port 8000
  • frontend — React/Vite development server on port 3000
  • postgres — PostgreSQL 15 database on port 5432
  • redis — Redis 7 for caching and Celery broker on port 6379
  • celery — Asynchronous task processing (FHIR sync, notifications)
  • celery-beat — Periodic task scheduler (billing calculations, compliance checks)

Run Database Migrations

Terminal 
# Apply all database migrations
docker compose exec backend python manage.py migrate

# Create the initial superuser account
docker compose exec backend python manage.py createsuperuser \
  --email admin@yourpractice.com

# (Optional) Load sample data for development
docker compose exec backend python manage.py create_default_roles

Collect Static Files

For the Django admin panel and API documentation to render correctly, collect static assets:

Terminal 
docker compose exec backend python manage.py collectstatic --noinput
Docker Setup Complete

Your instance is ready. Access the dashboard at http://localhost:3000, the API at http://localhost:8000/api/v1/, and the admin panel at http://localhost:8000/admin/.

Method 2: Native Development Setup

This method runs the backend and frontend directly on your machine. It provides faster hot-reload and allows direct debugger attachment from your IDE.

Prerequisites

Tool Minimum Version Installation
Python 3.11+ python.org/downloads
Node.js 20 LTS+ nodejs.org
npm 9+ Included with Node.js
PostgreSQL 15+ postgresql.org/download
Redis 7+ redis.io/download or brew install redis
Git 2.30+ git-scm.com/downloads

Backend Setup (Django)

Terminal 
# Clone and enter the project
git clone https://github.com/highlandpc/Vantrexia.git
cd Vantrexia

# Create and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate    # macOS/Linux
# venv\Scripts\activate     # Windows

# Install Python dependencies
pip install --upgrade pip
pip install -r backend/requirements.txt

# Copy and configure environment variables
cp .env.example .env

Edit .env to point to your local PostgreSQL and Redis instances:

.env 
# Database — update to match your local PostgreSQL
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/vantrexia_prod

# Redis — typically default local install
REDIS_URL=redis://localhost:6379/0

# Django
SECRET_KEY=your-secret-key-here-change-in-production
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

Database Initialization

Terminal 
# Create the PostgreSQL database
createdb vantrexia_prod

# Or via psql:
# psql -U postgres -c "CREATE DATABASE vantrexia_prod;"

# Run migrations
cd backend
python manage.py migrate

# Create superuser
python manage.py createsuperuser --email admin@yourpractice.com

# Collect static files
python manage.py collectstatic --noinput

Start the Backend

Terminal 
# Start Django development server
python manage.py runserver 0.0.0.0:8000

# In a separate terminal — start Celery worker
celery -A config worker --loglevel=info

# In another terminal — start Celery beat scheduler
celery -A config beat --loglevel=info --scheduler django_celery_beat.schedulers:DatabaseScheduler

Frontend Setup (React/Vite)

Terminal 
# From the project root
cd frontend

# Install Node.js dependencies
npm install

# Copy environment configuration

The frontend reads VITE_API_BASE_URL from environment. For local development the default (http://localhost:8000) works out of the box.

frontend/.env.local (optional) 
# Override only if API runs on a different host/port
VITE_API_BASE_URL=http://localhost:8000

Start the Frontend

Terminal 
# Start Vite development server with HMR
npm run dev

The frontend will be available at http://localhost:3000 with hot module replacement enabled.

Environment File Configuration

Vantrexia uses environment files to manage configuration across services. Here is the file structure:

File Purpose Method
backend/.env Django settings, database, Redis, eCW credentials, security keys Both
frontend/.env.local API URL, feature flags, app name Both
docker-compose.yml Service definitions, port mapping, volumes Docker only
docker-compose.prod.yml Production overrides (Nginx, SSL, replicas) Docker only
docker-compose.hipaa.yml HIPAA-hardened overrides (encryption, audit logging) Docker only
Security Notice

Never commit .env files to version control. The .gitignore is pre-configured to exclude them. For production deployments, use a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or GitHub Actions secrets.

Verifying the Installation

Run the following checks to confirm all services are operational:

1. API Health Check

Terminal 
curl -s http://localhost:8000/health/ | python3 -m json.tool

Expected output:

JSON 
{
    "status": "healthy",
    "version": "1.0.0",
    "database": "connected",
    "redis": "connected",
    "celery": "active",
    "timestamp": "2026-02-06T12:00:00Z"
}

2. Frontend Accessibility

Open http://localhost:3000 in your browser. You should see the Vantrexia login page. Sign in with your superuser credentials.

3. Django Admin

Navigate to http://localhost:8000/admin/ and verify you can log in and see the admin models (Patients, Observations, Users, etc.).

4. API Authentication Test

Terminal 
# Obtain a JWT token pair
curl -X POST http://localhost:8000/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@yourpractice.com", "password": "your-password"}'

# Use the access token to list patients
curl http://localhost:8000/api/v1/patients/ \
  -H "Authorization: Bearer <your-access-token>"

5. Run the Test Suite

Terminal 
# Docker method
docker compose exec backend python -m pytest --tb=short -q

# Native method (from backend/ directory)
python -m pytest --tb=short -q

All tests should pass. If any fail, check that all environment variables are set correctly and that PostgreSQL and Redis are accessible.

Common Installation Issues

Port Already in Use

If port 8000 or 3000 is occupied by another process:

Terminal 
# Find the process using port 8000
lsof -i :8000

# Kill it if necessary
kill -9 <PID>

Docker Permission Denied

On Linux, if you get a permission error, add your user to the docker group:

Terminal 
sudo usermod -aG docker $USER
newgrp docker

Database Connection Refused

Ensure PostgreSQL is running and accepting connections on port 5432. For the native setup, verify DATABASE_URL in backend/.env matches your local PostgreSQL credentials.

Node.js Version Mismatch

If you encounter frontend build errors, verify your Node.js version. We recommend using nvm to manage versions:

Terminal 
nvm install 20
nvm use 20
node --version  # Should output v20.x.x

For additional issues, see the Troubleshooting Guide.