Skip to content

Configuration

Since the server implementation is built with FastAPI, which uses pydantic, the configuration is based on pydantic's Setting management. This way of handling configuration options supports various different approaches to configure the server. We recommend either or a combination of the following:

  1. Set environment variables.
  2. Create a JSON file with an implementation's complete configuration.

When adding a third, final option, this also represents the (descending) order of priority with which configuration values are determined:

The JSON configuration file

The main way of configuring the OPTIMADE server is by creating a configuration JSON file.

An example of one that works with the example implementation can be found in optimade_config.json:

{
    "debug": false,
    "default_db": "test_server",
    "base_url": "http://localhost:5000",
    "implementation": {
        "name": "Example implementation",
        "source_url": "https://github.com/Materials-Consortia/optimade-python-tools",
        "maintainer": {"email": "dev@optimade.org"}
    },
    "provider": {
        "name": "Example provider",
        "description": "Provider used for examples, not to be assigned to a real database",
        "prefix": "exmpl",
        "homepage": "https://example.com"
    },
    "index_base_url": "http://localhost:5001",
    "provider_fields": {
        "structures": [
            "band_gap",
            "chemsys"
        ]
    },
    "aliases": {
        "structures": {
            "id": "task_id",
            "immutable_id": "_id",
            "chemical_formula_descriptive": "pretty_formula",
            "chemical_formula_reduced": "pretty_formula",
            "chemical_formula_anonymous": "formula_anonymous"
        }
    },
    "length_aliases": {
        "structures": {
            "chemsys": "nelements"
        }
    }
}

Environment variables

In order for the implementation to know where your configuration JSON file is located, you can set an environment variable OPTIMADE_CONFIG_FILE with the value of the full path to the JSON file.

This variable is actually an extension of the configuration option config_file. By default, the server will try to load a JSON file called .optimade.json located in your home folder (or equivalent).

Here the generally recognized environment variable prefix becomes evident, namely OPTIMADE_ or optimade_. Hence, you can set (or overwrite) any configuration option from the server's defaults or a value read from the configuration JSON by setting an environment variable named OPTIMADE_<configuration_option>.

List of configuration options

See config.py for a complete list of configuration options.

The following configuration file represents the default values for all configuration options:

{
    "config_file": "~/.optimade.json",
    "debug": false,
    "use_real_mongo": false,
    "mongo_database": "optimade",
    "mongo_uri": "localhost:27017",
    "links_collection": "links",
    "references_collection": "references",
    "structures_collection": "structures",
    "page_limit": 20,
    "page_limit_max": 500,
    "default_db": "test_server",
    "base_url": null,
    "implementation": {
        "name": "OPTIMADE Python Tools",
        "version": "0.13.2",
        "source_url": "https://github.com/Materials-Consortia/optimade-python-tools",
        "maintainer": {"email": "dev@optimade.org"}
    },
    "index_base_url": null,
    "provider": {
        "name": "Example provider",
        "description": "Provider used for examples, not to be assigned to a real database",
        "prefix": "exmpl",
        "homepage": "https://example.com"
    },
    "provider_fields": {},
    "aliases": {},
    "length_aliases": {},
    "index_links_path": "./optimade/server/index_links.json",
    "log_level": "info",
    "log_dir": "/var/log/optimade/"
}