Skip to content

Install

Jump to bottom
Dave Lawrence edited this page Jul 30, 2026 · 58 revisions

The dependency installer is tested on Ubuntu 20, 22, 24 and 26 (see the header of scripts/install/ubuntu_install_dependencies.sh). Instructions below assume a recent Ubuntu.

You need Git to download the repo

sudo apt-get install git

Development

For local development, you probably just want to use your normal account:

# Wherever you want to install repo, eg cd ~/localwork
git clone https://github.com/SACGF/variantgrid

Settings File

Variantgrid will have many of its settings in a file, typically looked for at /etc/variantgrid/settings_config.json This will include database passwords and other sensitive information that shouldn't be in source control.

config/settings_config.json in the repo is a template you can copy as a starting point (the "Code" step below does this) — see Settings for what each section does.

Server

For a server, create a "variantgrid" user to run the services:

# Server only
export SYSTEM_VARIANTGRID_USER=variantgrid
sudo id -u ${SYSTEM_VARIANTGRID_USER} &>/dev/null || sudo useradd ${SYSTEM_VARIANTGRID_USER} --create-home --shell /bin/bash
sudo mkdir -p /opt/variantgrid  # Or /mnt/variantgrid
sudo chown variantgrid /opt/variantgrid
sudo su variantgrid
cd /opt/
git clone https://github.com/SACGF/variantgrid variantgrid

Code

# Installs system dependencies via apt-get (Python packages are installed separately, into a venv)
sudo variantgrid/scripts/install/ubuntu_install_dependencies.sh
# Copy secret settings file
sudo mkdir /etc/variantgrid
sudo cp variantgrid/config/settings_config.json /etc/variantgrid

Now create the virtual environment and install the Python requirements — see Install Python venv. Every python3 manage.py ... command below assumes you have activated it.

If you are deploying to a server, create settings in "env" directory:

cd variantgrid
# Create settings file for this machine (lowercase hostname with dashes removed)
cp variantgrid/settings/env/_settings_template.py variantgrid/settings/env/$(hostname | tr '[:upper:]' '[:lower:]' | tr -d -).py

For developers, keep your config out of source control by putting it in "env_developers"

cd variantgrid
# Create settings file for this machine (lowercase hostname with dashes removed)
mkdir -p variantgrid/settings/env_developers
cp variantgrid/settings/env/_settings_template.py variantgrid/settings/env_developers/$(hostname | tr '[:upper:]' '[:lower:]' | tr -d -).py

Database

# Create DB and users, add extensions
sudo su postgres -c "psql < variantgrid/scripts/dbscripts/pgsql_database_create.sql"

From a default Ubuntu 24 install you will need to edit:

Change /etc/postgresql/${postgres_version}/main/postgresql.conf

# Uncomment line below
listen_addresses = 'localhost'         # what IP address(es) to listen on;

Modify file /etc/postgresql/${postgres_version}/main/pg_hba.conf

# change local/all/all to be a hash not 'peer' - so you can use passwords to login
local   all             all                                     scram-sha-256

Then for changes to take effect:

systemctl restart postgresql

To test - you should be able to connect to postgresql via the user/password in /etc/variantgrid/settings_config.json ie this (assuming using snpdb) should work:

psql --user snpdb -d snpdb -W

At this point, you can either restore a DB from a dump (see below) or run

python3 manage.py migrate

then run:

python3 manage.py createsuperuser
./scripts/upgrade.sh # Then run "auto", then afterwards any manual jobs

Especially for production use, you'll need to adjust the Settings

For MacOS see Install on MacOS

Required Components

Final Setup

Optional Components

See also

Clone this wiki locally