Skip to content

Settings

Jump to bottom
Dave Lawrence edited this page Aug 6, 2026 · 5 revisions

Django uses a settings file for configuration, which is plain Python code. VariantGrid uses this to configure optional features, eg:

USE_FEATURE_ONE = True

then in code:

from django.conf import settings

if settings.USE_FEATURE_ONE:
    # feature_one(data)

Host specific config

DJANGO_SETTINGS_MODULE defaults to variantgrid.settings, which detects the hostname and loads the matching module. The hostname is lowercased with dashes removed, and two locations are tried in order:

  1. variantgrid/settings/env_developers/<hostname>.py
  2. variantgrid/settings/env/<hostname>.py

You can also set DJANGO_SETTINGS_MODULE explicitly (eg variantgrid.settings.env.vgtest) to bypass detection.

The top of your settings file imports the component defaults:

from variantgrid.settings.components.annotation_settings import *
from variantgrid.settings.components.celery_settings import *
from variantgrid.settings.components.default_settings import *
from variantgrid.settings.components.seqauto_settings import *

The components are:

  • default_settings.py — all base Django settings
  • celery_settings.py — RabbitMQ/Celery queues and task routing
  • annotation_settings.py — VEP paths and annotation config (see Annotation Column Versions)
  • seqauto_settings.py — sequencing automation

Further lines can be used to add or alter any settings you need. Start from variantgrid/settings/env/_settings_template.py, which has commented examples for the common customisations (VEP version, genome builds, RefSeq vs Ensembl).

Developer settings

Only use settings "env" dir for server deployments

For developer settings - you can keep these out of source control by putting them in variantgrid/settings/env_developers rather than env (this is hidden via Git ignore)

Secret settings

Keep secret settings (users/passwords/API keys) out of source control, and load them via get_secret(). It checks environment variables first, then falls back to /etc/variantgrid/settings_config.json, using dotted paths for nested keys:

Setting up /etc/variantgrid/settings_config.json

config/settings_config.json in the repo is the template — copy it into place and lock it down, as it holds your database password:

sudo mkdir -p /etc/variantgrid
sudo cp config/settings_config.json /etc/variantgrid/
# Server: give it to the user that runs VariantGrid (web + Celery workers both read it)
sudo chown variantgrid /etc/variantgrid/settings_config.json
sudo chmod 600 /etc/variantgrid/settings_config.json

On a fresh install the values worth checking before you start anything are:

  • DB — must match the database you created with scripts/dbscripts/pgsql_database_create.sql (which makes user snpdb with password snpdb). If you changed the password there, change it here. psql --user snpdb -d snpdb -W is the test that the two agree — see Install.
  • CELERY.broker_url — the default amqp://guest:guest@localhost is RabbitMQ's guest account, which only works from localhost. Separate worker machines need a real RabbitMQ user here.
  • ENTREZ.email / api_key — NCBI asks for a contact email for citation lookups, and the API key raises the rate limit.
  • CLINGEN_ALLELE_REGISTRY — allele registration and Liftover via ClinGen. The template ships the shared VariantGrid login.
  • Anything you're not using can stay null — this is JSON, so null / true / false, not Python's None / True / False.

A file that doesn't parse is not an error you'll see at startup — the load failure is logged at INFO and every key silently falls back to the built-in defaults in variantgrid/settings/components/secret_settings.py (_default_settings). After editing:

python3 -m json.tool /etc/variantgrid/settings_config.json > /dev/null && echo OK

To see what a running deployment actually resolved a key to:

python3 manage.py shell -c 'from variantgrid.settings.components.secret_settings import get_secret; print(get_secret("DB.name"))'

A key with no default and no entry raises ValueError naming the key and the file it looked in, so missing config fails loudly with the fix in the message.

To keep the file somewhere else (eg a container mount), set the SETTINGS_CONFIG environment variable to its path.

Reading secrets in code

# get_secret / get_secrets come from default_settings' wildcard import, so no extra import needed
OIDC_RP_CLIENT_SECRET = get_secret('OIDC.client_secret')

There's also get_secrets(prefix, leafs) for pulling several keys under one prefix at once. Both take mandatory=False if a missing value is acceptable.

Sections in the template

  • DB — host / name / user / password
  • CELERY — broker_url
  • CLINGEN_ALLELE_REGISTRY — login / password (used for Liftover and allele registration)
  • ENTREZ — api_key / email
  • ROLLBAR — error reporting tokens
  • RECAPTCHA — public / private key (self-registration)
  • MME — Matchmaker Exchange tokens
  • SECURITY — eg maintenance_mode
  • SLACK — notifications
  • SYNC — Shariant / variantgrid.com sync credentials, and AWS S3 keys
  • SAPATH — SA Pathology specific integrations

Sections you add as needed (documented in the docstring in secret_settings.py) include OIDC (client secret, see Keycloak Integration), KEYCLOAK (admin API credentials) and AWS.SES (email sending).

Don't paste real tokens into this wiki or anywhere else public — read them from settings_config.json.

See also

Clone this wiki locally