Skip to content

Install

Jump to bottom
Dave Lawrence edited this page Aug 26, 2026 · 62 revisions

Shared steps for both installs. Start from Install (Developer) or Install (Server) — each covers getting the code, the secret settings file and this machine's settings, then sends you here, then finishes off with what only that path needs.

Database

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

From a default Ubuntu install you will need to edit the Postgres config. Take a copy of each file before you change it.

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

Postgres defaults to peer authentication for local connections, which authenticates you as the system user of the same name. VariantGrid connects as the snpdb database user with a password, so change the local line (around line 123) from peer:

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

/etc/postgresql/${postgres_version}/main/postgresql.conf only needs editing if something outside this machine connects to the database — eg Celery workers on a separate box. A single-machine install can leave it alone:

# Uncomment line below (and widen the address if you need remote connections)
listen_addresses = 'localhost'         # what IP address(es) to listen on;

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 — do that now, see Install from database dump — or start from the empty database you just created.

Either way, bring the schema up to date next:

python3 manage.py migrate

Migrations have to be applied before anything else touches the database — createsuperuser will fail against a database with unapplied migrations.

python3 manage.py createsuperuser

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

For MacOS see Install on MacOS

Required Components

Both of these write into /data/annotation (settings.ANNOTATION_BASE_DIR), which needs to exist and be owned by the user you run VariantGrid as before you start — see Install Annotation.

Finishing the install with the upgrader

Once VEP and the annotation data are in place, run the upgrader — it applies the standard steps and lists any one-off tasks this version needs:

./scripts/upgrade.sh

With no argument you get the interactive menu:

  • a — the standard steps: git pull, migrate, collectstatic_js_reverse, collectstatic, deployment_check, deployed
  • am — auto-run all outstanding manage.py steps that aren't waiting on a gate
  • Numbered entries under ****** SPECIAL STEPS ****** — the one-off tasks for this version. Each runs on its own; when it finishes the menu is redrawn with the remaining tasks renumbered, so the next one to run is again 1.

Run a first. The last standard step is deployment_check --die-if-invalid, which validates VEP, annotation data files, cdot transcripts and tool versions — so it fails until Install VEP and Install Annotation are done. If a standard step fails, fix the cause before moving on to the special steps rather than working around it.

Then run the special steps, either one at a time from the menu, or all at once:

./scripts/upgrade.sh --auto-manage

See Upgrading for the full description of the upgrade tool.

Configuring your installation

The defaults give you a single-genome-build (GRCh37) research install with every app visible. From here:

Optional Components

Back to your install

That is the shared part done — return to Install (Developer) or Install (Server) to finish.

See also

Clone this wiki locally