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.
Initialize
Section titled “Initialize”refgenie initThis 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.
Environment variables
Section titled “Environment variables”| Variable | Default | Purpose |
|---|---|---|
REFGENIE_HOME_PATH | ~/.refgenie | Base directory for all refgenie files |
REFGENIE_LOG_LEVEL | WARNING | Logging verbosity |
REFGENIE_GENOME_FOLDER | $REFGENIE_HOME_PATH/genomes | Directory for genome assets |
REFGENIE_GENOME_STAGE_FOLDER | $REFGENIE_HOME_PATH/archives | Directory for staged assets |
REFGENIE_DB_CONFIG_PATH | $REFGENIE_HOME_PATH/refgenie_db_config.yaml | Path to the database config file |
REFGENIE_SUBSCRIBE_DEFAULT_SERVER | true | Subscribe a new configuration to https://api.refgenie.org |
REFGENIE_CONTAINER_ENGINE | auto | What runs a recipe's container image: docker, apptainer, or auto (Docker when its daemon answers, else Apptainer) |
REFGENIE_APPTAINER_CACHEDIR | unset | Passed to Apptainer as APPTAINER_CACHEDIR, so image pulls land there instead of under $HOME |
For example:
export REFGENIE_GENOME_FOLDER=~/my_genomesexport REFGENIE_DB_CONFIG_PATH=~/my_refgenie_db_config.yamlComing 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.
Database
Section titled “Database”The database config file selects SQLite or PostgreSQL. See Database backends for the file format and when to use each.
Servers
Section titled “Servers”Subscribe to servers to pull assets and look up remote paths. You can also manage subscriptions on the Servers page of refgenie dash.
refgenie subscribe -s https://my-lab-server.example.orgrefgenie unsubscribe -s https://my-lab-server.example.orgInspect the configuration
Section titled “Inspect the configuration”refgenie config getThis 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: nullConfigure from Python
Section titled “Configure from Python”The Refgenie constructor takes these options:
database_config_path: path to a database config file, instead ofREFGENIE_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 aRefgenieserverClientfromrefgenie.managers.sources.client.
from sqlalchemy import create_enginefrom refgenie import Refgenie
engine = create_engine("postgresql+psycopg://user:password@host:5432/dbname")rgc = Refgenie(database_engine=engine)