Docker Installation¶

The REST VariantValidator API depends on the VariantValidator backend services. Before building and running the API, these services must be installed and started.

The required backend services are:

Validator Database (MySQL)
VVTA Transcript Archive (PostgreSQL)
SeqRepo

These services only need to be installed once. Once created, they can be started and stopped without rebuilding the Docker images.

Installing the Backend Services¶

Requirements¶

Docker
Git

Clone the VariantValidator repository¶

git clone https://github.com/openvar/VariantValidator.git
cd VariantValidator

Create a Docker network¶

docker network create variantvalidator-network

Build and start the VVTA PostgreSQL database¶

docker build \
    --no-cache \
    -f db_dockerfiles/vvta/Dockerfile \
    -t postgres-vvta \
    db_dockerfiles/vvta

docker run -d \
    --name vv-vvta \
    --network variantvalidator-network \
    --shm-size=2g \
    -p 54320:5432 \
    postgres-vvta

Build and start the Validator MySQL database¶

docker build \
    --no-cache \
    -f db_dockerfiles/vdb/Dockerfile \
    -t mysql-validator \
    db_dockerfiles/vdb

docker run -d \
    --name vv-vdb \
    --network variantvalidator-network \
    -p 33060:3306 \
    mysql-validator

Build the SeqRepo image¶

docker build \
    --no-cache \
    -f db_dockerfiles/vvsr/Dockerfile \
    -t seqrepo-validator \
    db_dockerfiles/vvsr

Extract the SeqRepo data¶

Create a temporary container and copy the SeqRepo data onto the host.

sudo mkdir -p /usr/local/share/seqdata

docker create \
    --name vv-seqrepo-temp \
    seqrepo-validator

sudo docker cp \
    vv-seqrepo-temp:/usr/local/share/seqdata/. \
    /usr/local/share/seqdata

docker rm vv-seqrepo-temp

Verify the SeqRepo installation¶

ls /usr/local/share/seqdata

The directory should contain the extracted SeqRepo data.

Wait for the databases to initialise¶

Wait for MySQL¶

until docker exec vv-vdb \
    mysqladmin ping \
    -u vvadmin \
    -pvar1ant \
    --silent
do
    sleep 5
done

echo "MySQL ready."

Wait for VVTA¶

until docker logs vv-vvta 2>&1 | \
    grep -q "PostgreSQL init process complete; ready for start up."
do
    sleep 10
done

echo "VVTA ready."

Once these services are running, continue with the REST VariantValidator installation below.

Configure the REST API¶

Before building the REST VariantValidator API image, update local_docker.ini so that it points to the backend services installed in the previous steps.

An example configuration is shown below:

[mysql]
host = host.docker.internal
port = 3306
database = validator
user = vvadmin
password = Var1antVal1d!
version = vvdb_2025_3

[seqrepo]
version = VV_SR_2025_02/master
location = /data/variantvalidator/
require_threading = True

[postgres]
host = host.docker.internal
port = 5432
database = vvta
version = vvta_2025_02
user = uta_admin
password = uta_admin

[logging]
log = True
console = WARNING
file = ERROR

[Entrez]
email = email
api_key = key

Required changes¶

Update the following settings to match the backend services created during installation.

MySQL¶

The Docker Quick Start exposes the Validator database on port 33060, so update:

host = host.docker.internal
port = 33060

The remaining values should normally remain unchanged:

database = validator
user = vvadmin
password = Var1antVal1d!
version = vvdb_2025_3

If you have installed a newer Validator database release, update the version field accordingly.

PostgreSQL (VVTA)¶

The Docker Quick Start exposes the VVTA database on port 54320, so update:

host = host.docker.internal
port = 54320

The remaining values should normally remain unchanged:

database = vvta
user = uta_admin
password = uta_admin
version = vvta_2025_02

If you have installed a newer VVTA release, update the version field accordingly.

SeqRepo¶

The REST API expects the SeqRepo data to be mounted inside the container at:

location = /data/variantvalidator/

This path should match the Docker bind mount used when starting the container.

Update the version field if you are using a newer SeqRepo release.

Entrez¶

Replace the example values with your own NCBI credentials:

email = your.email@example.org
api_key = your_ncbi_api_key

An API key is optional but strongly recommended, as it increases the request rate permitted by the NCBI Entrez services.

Configuration summary¶

If you have followed this guide exactly, the configuration should be updated to:

[mysql]
host = host.docker.internal
port = 33060
database = validator
user = vvadmin
password = Var1antVal1d!
version = vvdb_2025_3

[seqrepo]
version = VV_SR_2025_02/master
location = /data/variantvalidator/
require_threading = True

[postgres]
host = host.docker.internal
port = 54320
database = vvta
version = vvta_2025_02
user = uta_admin
password = uta_admin

[logging]
log = True
console = WARNING
file = ERROR

[Entrez]
email = your.email@example.org
api_key = your_ncbi_api_key

Note: If you chose different Docker port mappings during installation, update the mysql.port and postgres.port settings accordingly. The configuration file must always match the ports exposed by your Docker containers.

VariantValidator SHAIP – Docker Build & Run Instructions¶

This Dockerfile supports:

Development builds (local testing)
Production builds (default – no build arguments required)

Build Modes¶

Production Mode (default)¶

Uses the TerraCipher base image and production configuration.

Build¶

docker build -t vv-prod .

Run¶

docker run --rm \
    -p 8080:8080 \
    vv-prod

Notes

No build arguments are required.
This is the recommended configuration for TerraCipher AWS deployments.
VariantValidator and VariantFormatter are initialised automatically when first used.

Development Mode (local installation)¶

Uses a clean Python base image together with the local configuration.

Build¶

docker build \
    --no-cache \
    --build-arg BUILD_TARGET=local \
    --build-arg BASE_IMAGE=python:3.12.11-slim-bookworm \
    -t vv-local .

Run¶

docker run --rm \
    -p 8080:8080 \
    -v /Users/<you>/variantvalidator_data/seqdata:/data/variantvalidator \
    -v /Users/<you>/.restvv_auth.ini:/root/.restvv_auth.ini:ro \
    vv-local

Notes¶

Production mode is the default when no BUILD_TARGET is specified.
Development mode must be explicitly selected using BUILD_TARGET=local.
BASE_IMAGE overrides are intended for development builds only.
Using --workers 3 provides optimal performance, as the validator is loaded once and shared between worker processes.
TerraCipher AWS deployments should use the default production build.
The REST API expects the VariantValidator backend services (VVDB, VVTA and SeqRepo) to be running before the container is started.

Restarting an Existing Installation¶

Once the backend services have been created, they can be restarted without rebuilding.

docker start vv-vdb vv-vvta

The REST API container can then be started in the normal way.

Stopping the Services¶

Stop the backend services:

docker stop vv-vdb vv-vvta

Stop the REST API container as required.

Cleaning Up¶

To remove the backend services:

docker stop vv-vdb vv-vvta || true

docker rm vv-vdb vv-vvta || true

docker network rm variantvalidator-network || true

To additionally remove the Docker images:

docker rmi mysql-validator postgres-vvta seqrepo-validator vv-local vv-prod