Skip to content

Configure refgenie

Refgenie keeps its settings in a database (SQLite or PostgreSQL) and reads a few environment variables for paths and behavior. The settings include the genome folder, the stage folder, subscribed servers, data channels, and remotes.

Terminal window
refgenie init

This creates ~/.refgenie/ with a SQLite database, a genomes/ folder, and a database config file. It also subscribes to the default server, https://api.refgenie.org, so refgenie pull works right away. To start with no subscriptions, run refgenie init --no-default-server or set REFGENIE_SUBSCRIBE_DEFAULT_SERVER=false. Running refgenie init again leaves existing subscriptions as they are.

VariableDefaultPurpose
REFGENIE_HOME_PATH~/.refgenieBase directory for all refgenie files
REFGENIE_LOG_LEVELWARNINGLogging verbosity
REFGENIE_GENOME_FOLDER$REFGENIE_HOME_PATH/genomesDirectory for genome assets
REFGENIE_GENOME_STAGE_FOLDER$REFGENIE_HOME_PATH/archivesDirectory for staged assets
REFGENIE_DB_CONFIG_PATH$REFGENIE_HOME_PATH/refgenie_db_config.yamlPath to the database config file
REFGENIE_SUBSCRIBE_DEFAULT_SERVERtrueSubscribe a new configuration to https://api.refgenie.org
REFGENIE_CONTAINER_ENGINEautoWhat runs a recipe's container image: docker, apptainer, or auto (Docker when its daemon answers, else Apptainer)
REFGENIE_APPTAINER_CACHEDIRunsetPassed to Apptainer as APPTAINER_CACHEDIR, so image pulls land there instead of under $HOME

For example:

Terminal window
export REFGENIE_GENOME_FOLDER=~/my_genomes
export REFGENIE_DB_CONFIG_PATH=~/my_refgenie_db_config.yaml

Coming from refgenie 0.x? The $REFGENIE variable that pointed to the 0.x config file is ignored in 1.x, which uses REFGENIE_HOME_PATH and REFGENIE_DB_CONFIG_PATH instead. To move an existing setup, see Upgrade from legacy.

The README lists the variables for the server, dashboard, and plugins too.

The database config file selects SQLite or PostgreSQL. See Database backends for the file format and when to use each.

Subscribe to servers to pull assets and look up remote paths. You can also manage subscriptions on the Servers page of refgenie dash.

Terminal window
refgenie subscribe -s https://my-lab-server.example.org
refgenie unsubscribe -s https://my-lab-server.example.org
Terminal window
refgenie config get

This prints YAML in two blocks. configuration holds the settings stored in the database (genome folder, stage folder, subscribed servers, plugin settings). environment holds the settings that come from environment variables, or their defaults:

configuration:
version: 1
genome_folder: /home/user/.refgenie/genomes
servers:
- https://api.refgenie.org
genome_stage_folder: /home/user/.refgenie/archives
plugin_settings: {}
environment:
log_level: WARNING
genome_folder: /home/user/.refgenie/genomes
genome_stage_folder: /home/user/.refgenie/archives
database_config_path: /home/user/.refgenie/refgenie_db_config.yaml
disable_plugins: ''
server_plugins: false
subscribe_default_server: true
container_engine: auto
apptainer_cachedir: null

The Refgenie constructor takes these options:

  • database_config_path: path to a database config file, instead of REFGENIE_DB_CONFIG_PATH.
  • database_engine: a SQLAlchemy engine you already have, such as a pooled connection or a test database. If you pass both, the engine wins.
  • server_clients_mapping: a dict of server URL to client object, for custom or mock server clients. Each client is a RefgenieserverClient from refgenie.managers.sources.client.
from sqlalchemy import create_engine
from refgenie import Refgenie
engine = create_engine("postgresql+psycopg://user:password@host:5432/dbname")
rgc = Refgenie(database_engine=engine)