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. Create a JSON or YAML configuration file with an implementation's complete configuration in the default location DEFAULT_CONFIG_FILE_PATH or specify its location with the OPTIMADE_CONFIG_FILE environment variable.
2. Set environment variables prefixed with OPTIMADE_ or optimade_.
3. Create a custom ServerConfig object with the desired settings directly.
4. Load settings from a secret file (see pydantic documentation for more information).

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 either the value of the absolute path to the configuration file or the relative path to the file from the current working directory of where the server is run.

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>.

Custom configuration options¶

One can extend the current list of configuration options by sub-classing ServerConfig and adding configuration options as attributes with values of Field (pydantic.field). Any attribute type will be validated through pydantic as is the case for all of the regular configuration options.

This is useful for, e.g., custom database backends, if one wants to utilize the general server configuration setup implemented in optimade to declare specific database information. It can also be useful if one wishes to extend and build upon the general optimade server with new endpoints and routes.

Remember to instantiate an instance of the sub-class, which can be imported and used in your application.

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,
    "insert_test_data": true,
    "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.15.4",
        "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/"
}