Configuration#

This guide explains how to handle configurations in your OrangeQS Juice extension. There are three main aspects to configuration management in OrangeQS Juice:

Note

This guide is meant as a tutorial, see How configurations are stored and loaded in the Reference guide for an extensive reference.

Configuration file organization#

The OrangeQS Juice configuration consists of many independent configurable schemas. OrangeQS Juice stores configurations in .toml files with unique filenames per schema. Configuration files have the following patterns:

  • <filename.toml>: the base configuration.

  • <filename>.d/*.toml: specific overrides.

Each configurable schema has a unique filename associated with it. The filename should be unique across the entire Orange Juice installation. A filename always maps to exactly one configuration schema. It’s recommended to prefix filenames with the extension name to prevent conflicts.

OrangeQS Juice automatically loads configuration files from multiple locations.

  • System-wide configuration: The system-wide /etc/juice/config directory, which contains configuration files managed by the system administrator.

  • OrangeQS Juice extensions: Specially marked config directories that are bundled inside installed OrangeQS Juice extensions.

The contents of the configuration files are merged recursively per filename. Dictionaries are merged by each key separately, but lists will be replaced entirely by higher priority files. The configuration files are prioritized in the following order, meaning later files will override previous files:

/etc/juice/config / <filename>.toml
/etc/juice/config / <filename>.d / *.toml
      <extension> / <filename>.toml
      <extension> / <filename>.d / *.toml

Warning

An exception to this rule is the orchestration.toml configuration file, which can only be loaded from /etc/juice/config. This configuration file can thus only be modified by the system administrator.

Hint

The configuration system also supports overriding the default priorities. This is an advanced feature and described in the Configuration file loading paths

Exposing configuration options for your extension#

This section explains how to make your extension configurable by defining configuration schemas that others can customize.

To expose configuration options for your extension, you need to subclass the Configurable class. This class is a pydantic.BaseModel and uses pydantic for schema definition and data validation. As an example, let’s define a configuration for a HTTP server:

from typing import ClassVar
from orangeqs.juice.settings import Configurable

class ExampleHTTPServerSettings(Configurable):
    """HTTP configuration for the example extension."""

    # The unique key which defines the name of the configuration files.
    # This field is always required.
    filename: ClassVar[str] = "example-http-server"

    # A configuration value of type `int` and default value 8123.
    port: int = 8123
    """The port to run the HTTP server on."""

Note that the Configurable.filename class variable is always required. This unique filename determines which configuration files on disk will be loaded for this configuration class.

To load the configuration from disk, use the Configurable.load() method:

# Load configuration from disk
config = ExampleHTTPServerSettings.load()

# If no configuration files exist yet, the config will contain default values
assert config.port == 8123

Bundling configuration files with your extension#

This section explains how to bundle configuration files with your extension that configure other parts of OrangeQS Juice.

Why bundle configuration files?#

While you can define default values for your own extension’s configuration schema in the class definition, you cannot directly modify other extensions’ class definition. Bundling configuration files with your extension allows you to:

  • Add resources like InfluxDB buckets, dashboard widgets, or monitoring configurations.

  • Modify settings of other extensions, like ports or file locations.

  • Injecting your features into another extension, like configuring the device service to user your device implementation.

This feature allows your extension to integrate tightly with the entire OrangeQS Juice installation.

Setting up configuration file bundling#

To bundle configuration files with your extension, you need to:

  1. Configure the entry point in your pyproject.toml to tell Juice where to find your configuration files

  2. Configure setuptools to include the .toml files in your Python package

You can do this by adding the following to your pyproject.toml:

# pyproject.toml

# 1. Tell Juice where to find configuration files.
[project.entry-points."juice.config"]
# Load all configuration files from the src/juice_extension_example/config directory.
config = "juice_extension_example.config"

# 2. Tell setuptools which files to include in the package
[tool.setuptools.package-data]
# Include all `.toml` files in the src/juice_extension_example/config directory.
"juice_extension_example.config" = ["*.toml"]

See the setuptools entry points and data files documentation for more information.

Creating bundled configuration files#

Now you can create configuration files in the src/juice_extension_example/config directory that will be automatically loaded when your extension is installed.

Not implemented yet!

This section is part of documentation-driven development, thus its contents are not yet functional and open for feedback!

For example, let’s add a configuration file that configures InfluxDB to create a bucket for HTTP server logs:

# src/juice_extension_example/config/influxdb.toml

[buckets.example_http_server]
retention_policy = "1w"

When your extension is installed, this configuration will be automatically loaded and the InfluxDB bucket will be created.

You could also create configuration files that:

  • Configure your own extension with sensible defaults: example-http-server.toml

  • Add dashboard widgets: dashboard.d/my-widget.toml

  • Configure system monitoring: system-monitor.toml

  • Modify settings of other extensions: other-extension.toml

The juice config CLI

See also the juice config CLI which provides commands to interact with the configuration.