This page was composed with the aid of generative artificial intelligence; it is partially curated.

Installation Guide

Detailed installation instructions for different deployment scenarios.

System Requirements (minimum for VCF inputs; recommended for others)

CPU: 4 cores (8+ recommended)
RAM: 16 GB (64+ GB recommended)
Storage: 50 GB free space (1000+ GB recommended)
OS: Linux, macOS, or Windows with WSL2
Network: Stable internet needed for initial setup only (TODO: check nextflow behavior)
Docker and docker compose

Docker Installation

If you do not have docker and docker composed installed, the easiest way to get up and running is:
https://www.docker.com/products/docker-desktop/
This is particularly handy if you are on Windows w/ WSL2 or macOS.
On Windows, ensure WSL2 backend is enabled in Docker Desktop.
Otherwise, here’s an example for Debian/Ubuntu-based systems:

Ubuntu/Debian:

sudo apt update
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Verify Installation

docker --version
docker compose version

Deploy ZaroPGx via docker compose

1. Grab Repository

git clone https://github.com/Zaromics/ZaroPGx.git
cd ZaroPGx

2. Review environment configuration options

Choose an appropriate starting .env file: local|production|custom

Local:

Binds to localhost only
Development subnet (172.28.0.0/16)
Authentication disabled by default
Debug logging enabled

cp .env.local .env

Production:

Binds to all interfaces (0.0.0.0)
Production subnet
Authentication enabled
Optimized logging

cp .env.production .env

Custom

cp .env.example .env

3. Configure options via environment variables

Edit .env file with your settings:

# Required for production
SECRET_KEY=your-secret-key-here
# Database settings
POSTGRES_PASSWORD=your-db-password
# Optional: Customize ports
BIND_ADDRESS=8765
# Optional: Feature toggles
GATK_ENABLED=true
PYPGX_ENABLED=true
OPTITYPE_ENABLED=true

See Advanced Configuration for complete .env conf options.

4. Start Services

docker compose up -d --build && docker compose logs app -f

5. Verify Installation

Check service status:

docker compose ps

Service Ports

Service	Host Port	Container Port	Description
App/UI	8765	8000	Main web interface and API
Database	5444	5432	PostgreSQL database
PharmCAT	5001	5000	PharmCAT analysis service
GATK API	5002	5000	GATK preprocessing service
PyPGx	5053	5000	PyPGx allele calling service
FHIR Server	8090	8080	HAPI FHIR server
Kroki	8001	8000	Diagram rendering service

Initial Setup

1. Download Reference Data

The system will automatically download reference genomes on first run:

docker compose logs genome-downloader
ls -la reference/

2. Initialize Postgres Database

The database initializes automatically with:

CPIC guidelines and data
User management tables
Workflow tracking tables

3. Test Installation

Upload a test file:

curl -X POST \
  -F "file=@test_data/sample_cpic.vcf" \
  -F "sample_identifier=test_sample" \
  http://localhost:8765/upload/genomic-data

Troubleshooting

Common Issues

Port conflicts:

Check what’s using ports

netstat -tulpn | grep :8765

Change ports accordingly in .env

Permission errors:

sudo chown -R $USER:$USER .

Out of storage space:

Check drive space

df -h

Clean up docker files (make sure you back up anything important!)

docker system prune -a

Out of memory issues:

Increase Docker memory limit
In Docker Desktop: Settings → Resources → Memory

Logs and Debugging

View service logs:

docker compose logs -f

Next Steps

Advanced Configuration: Advanced Configuration
Usage Guide: User Guide
File Formats: Supported File Formats [NEEDS CURATION]
Deployment Guide: Deployment Guide