Environment Namespace

A quick summary of environment variables is shown below, and more details about specific variables provided after that.

Variable Default Definition
SREGISTRY_DATABASE $HOME/.singularity The base folder for the sregistry database
SREGISTRY_STORAGE $HOME/.singularity/shub The folder within SREGISTRY_DATABASE to store images
SINGULARITY_DISABLE_CACHE False Disable caching of Singularity build objects
SREGISTRY_DISABLE False Disable the database entirely, omits sqlalchemy dependency
SINGULARITY_CACHEDIR $HOME/.singularity We honor the Singularity client cache directory
SREGISTRY_CLIENT_SECRETS $HOME/.sregistry a json file, with keys as clients, values are client-specific parameters
SREGISTRY_HTTPS_NOVERIFY False Turn off certificate verification (not recommended)
SREGISTRY_CLIENT hub Remote client to interact with list with sregistry backend ls
SREGISTRY_TMPDIR temporary directory A temporary folder to build and pull containers
SREGISTRY_THUMBNAIL [install-dir]/database/robot.png A thumbnail for clients to use, if needed
SREGISTRY_DISABLE_CREDENTIAL_CACHE False Disable all caching of credentials (you will need to always set
SREGISTRY_PYTHON_THREADS 9 Number of threads to use for Multiprocessing (download of layers, generally)

Base Environment Defaults

The database path, an sqlite3 file, is determed based on the environment variable SREGISTRY_DATABASE. If not found, it will be written to our singularity cache folder, which is usually in our $HOME.


For storage of images, we use the same folder that Singularity will by default look for the cache.


And for either, if you want to change these locations you can export the variables. There is no reason that the database file needs to live next to the image folder, for example, and you might want to give it a unique name to a user, depending on your setup.

If you have exported the variable SINGULARITY_DISABLE_CACHE, an option with the Singularity command line software to not cache anything, SRegistry will honor this and not maintain a database. If you want to keep the cache but just disable the SRegistry database, then export SREGISTRY_DISABLE=yes.

Client Environment Variables

The sregistry client exposes a lot of customization through environment variables, so you as the user have the power to configure it exactly as you need, or stick to defaults that are reasonably set. In these sections, we will review the sets of environment variables for you to use across clients. If you want to peek at the environment variables being set for some client, you can do that:

$ sregistry backend ls registry
    "base": "",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "username": "dinosaur"

If you are a developer, there is a suite of environment variables provided that are intended to make interaction with existing functions easier! See our client contribution guide for details on interacting with these environment variables.

Http and Authentication

While most of the authentication variables live with the clients, sregistry offers a few Global settings to be applied to all web requests.

Database and Storage

The database refers to the sqlite3 file used to store metadata, typically in the user’s home, and the storage refers to the actual folder of images. You can control this behavior with the following environment variables.

tree $HOME/.singularity.shub

├── expfactory
│   └── expfactory-master:v2.0.simg
└── vsoch
    ├── hello-pancakes:latest.simg
    └── hello-world:latest.simg

The organization is trivial for sregistry because images are interacted with via uri (unique resource identifier). This is also a way to distinguish images that you have pulled via Singularity into the cache (and aren’t in your database) from those retrieved with sregistry, and organized and present in the database. For future versions of Singularity it would be ideal to give the user an option to add images in this format (and possibly add to the database, if the integration is available).

Credentials and Settings

Credentials broadly refer to tokens and secrets (authentication and refresh tokens, for example) needed by various clients to authenticate you to their services. The sregistry client has two storage strategies for handling credentials and settings.

Temporary Locations

For most clients, if we need to pull (or build) a container, we will do so in a temporary location that defaults to the result of tempfile.mkdtemp(), meaning a temporary folder. If you choose, you can export this to be a different location by setting SREGISTRY_TMPDIR. This will be used for all actions other than those that are driven by Singularity, which has its own environment variable namespace for pull and cache locations (e.g., SINGULARITY_CACHEDIR). If you want to customize: