(Updated) Configuration Management

Introduction

There have been some changes made to how Bacalhau handles configuration:

1. The bacalhau repo ~/.bacalhau no longer contains a config file.

2. Bacalhau no longer looks in the repo ~/.bacalhau for a config file.

3. Bacalhau never writes a config file to disk unless instructed by a user to do so.

4. A config file is not required to operate Bacalhau.

5. Bacalhau searches for a default config file. The location is OS-dependent:

   1. Linux: ~/.config/bacalhau/config.yaml

   2. OSX: ~/.config/Application\ Support/bacalhau/config.yaml

   3. Windows: $AppData\bacalhau\config.yaml. Usually, this is something like C:\Users\username\bacalhau\config.yaml

Summary

Bacalhau no longer relies on the ~/.bacalhau directory for configuration and only creates a config file when instructed. While not required, it will look for a default config file in OS-specific locations.

Inspecting the Current Configuration of Bacalhau

To view the configuration that bacalhau will receive when a command is executed against it, users can run the bacalhau config list command. Users who wish to see Bacalhau’s config represented as YAML may run bacalhau config list --output=yaml.

Making Changes to the Default Config File

As described above, bacalhau still has the concept of a default config file, which, for the sake of simplicity, we’ll say lives in ~/.config/bacalhau/config.yaml. There are two ways this file can be modified:

1. A text editor vim ~/.config/bacalhau/config.yaml.

2. The bacalhau config set command.

Using a Non-Default Config File.

The --config (or -c ) flag allows flexible configuration of bacalhau through various methods. You can use this flag multiple times to combine different configuration sources. To specify a config file to bacalhau, users may use the --config flag, passing a path to a config file for bacalhau to use. When this flag is provided bacalhau will not search for a default config, and will instead use the configuration provided to it by the --config flag.

Bacalhau Configuration Keys

In Bacalhau, configuration keys are structured identifiers used to configure and customize the behavior of the application. They represent specific settings that control various aspects of Bacalhau's functionality, such as network parameters, API endpoints, node operations, and user interface options. The configuration file is organized in a tree-like structure using nested mappings (dictionaries) in YAML format. Each level of indentation represents a deeper level in the hierarchy.

Example: part of the config file

API:
  Host: 0.0.0.0
  Port: 1234
  Auth:
    Methods:
      ClientKey:
      Type: challenge
NameProvider: puuid
DataDir: /home/frrist/.bacalhau
Orchestrator:
  Host: 0.0.0.0
  Port: 4222
  NodeManager:
    DisconnectTimeout: 1m0s

In this YAML configuration file:

1. Top-Level Keys (Categories): API, Orchestrator

2. Sub-Level Keys (Subcategories): Under API, we have Host and Port; Under Orchestrator we have Host, Port and NodeManager

3. Leaf Nodes (Settings): Host, Port, NameProvider, DataDir, DisconnectTimeout — these contain the actual configuration values.

Config keys use dot notation to represent the path from the root of the configuration hierarchy down to a specific leaf node. Each segment in the key corresponds to a level in the hierarchy. Syntax is Category.Subcategory(s)...LeafNode

Using Keys With config set, config list and --config

The bacalhau config list returns all keys and their corresponding value. The bacalhau config set command accepts a key and a value to set it to. The --config flag accepts a key and a value that will be applied to Bacalhau when it runs.

Example Interaction With the Bacalhau Configuration System

How to Modify the API Host Using bacalhau config set in the Default Config File:

1. Run bacalhau config list to find the appropriate key

bacalhau config list
 KEY VALUE DESCRIPTION
 ... ... ...
 api.host 0.0.0.0 Host specifies the hostname or IP address o
 ... ... ...

1. Run the bacalhau config set command

bacalhau config set api.host 192.186.0.1

1. Observe how bacalhau config list reflects the new setting

bacalhau config list
 KEY VALUE DESCRIPTION
 ... ... ...
 api.host 192.168.0.1 Host specifies the hostname or IP address
 ... ... ...

1. Observe the change has been reflected in the default config file

cat ~/.config/bacalhau/config.yaml
api:
    host: 192.168.0.1

How to Modify the API Host Using bacalhau config set a Custom Config File

1. Run the config set command with the flag

bacalhau config set --config=custom.yaml api.host 10.0.0.1

1. Observe the created config file

cat custom.yaml
api:
 host: 10.0.0.1

Observe the default config and output of bacalhau config list does not reflect this change.

How to Start Bacalhau With a Custom Config File

bacalhau --config=custom.yaml serve

Usage of the --config Flag

The --config (or -c) flag allows flexible configuration of bacalhau through various methods. You can use this flag multiple times to combine different configuration sources.

Usage

bacalhau [command] --config <option> [--config <option> ...] 

or using the short form:

bacalhau [command] -c <option> [-c <option> ...]

Configuration Options

1. YAML Config Files: Specify paths to YAML configuration files. Example:

--config path/to/config.yaml

1. Key-Value Pairs: Set specific configuration values using dot notation. Example:

--config WebUI.Enabled=true

1. Boolean Flags: Enable boolean options by specifying the key alone. Example:

--config WebUI.Enabled

Precedence

When multiple configuration options are provided, they are applied in the following order of precedence (highest to lowest):

1. Command-line key-value pairs and boolean flags

2. YAML configuration files

3. Default values

Within each category, options specified later override earlier ones.

Examples

Using a single config file:

bacalhau serve --config my-config.yaml

Merging multiple config files:

bacalhau serve -c base-config.yaml -c override-config.yaml

Overriding specific values:

bacalhau serve \
-c config.yaml \
-c WebUI.Listen=0.0.0.0:9999 \
-c NameProvider=hostname

Combining file and multiple overrides:

bacalhau serve \
-c config.yaml \
-c WebUI.Enabled \
-c API.Host=192.168.1.5

In the last example, WebUI.Enabled will be set to true, API.Host will be 192.168.1.5, and other values will be loaded from config.yaml if present.

Remember, later options override earlier ones, allowing for flexible configuration management.

Usage of the bacalhau completion Command

The bacalhau completion command will generate shell completion for your shell. You can use the command like:

bacalhau completion <bash|fish|powershell|zsh> > /tmp/bacalhau_completion && source /tmp/bacalhau_completion 

After running the above command, commands like bacalhau config set and bacalhau --config will have auto-completion for all possible configuration values along with their descriptions

Support

If you have questions or need support or guidance, please reach out to the Bacalhau team via Slack (#general channel).