Configuration¶

3LC has several configuration options, which control data discovery, logging, and network configuration.

The full reference, grouped by category, lives on the Configuration Options Reference page — each option lists its YAML key, environment variable, CLI argument and Python attribute side by side. The underlying tlcconfig.options module is the Python-level source of truth for the same metadata.

3LC tries to have as good defaults as possible, however some times you may want to persist a machine global configuration. This can be achieved by using the default configuration file. The configuration file is located in $HOME/.config/3LC/config.yaml on Linux and in %LOCALAPPDATA%\3LC\3LC\config.yaml on Windows. The location can be overridden by the TLC_CONFIG_FILE environment variable.

The 3lc config command group inspects and manages the configuration. The two main verbs are:

  • 3lc config show — print the current effective configuration. Use -f yaml to emit YAML (suitable for redirecting into a config file).

  • 3lc config project-root <URL> — set or update the project root in the user configuration file.

To create or refresh the user configuration file, redirect a YAML dump:

# Write the current effective configuration to the default user config file location
3lc config show -f yaml > "$HOME/.config/3LC/config.yaml"

3lc config show reads the current configuration — including environment variables and any 3lc command-line options supplied alongside — so you can layer overrides on a single invocation:

# Persist the project root in the user configuration file
3lc config project-root /some/location

# Persist an alias by emitting the resolved configuration to the user config file
TLC_ALIAS_CIFAR10_LOCATION="/some/location" 3lc config show -f yaml > "$HOME/.config/3LC/config.yaml"

Other useful subcommands: 3lc config validate (checks the current configuration) and 3lc config path (prints the resolved configuration-file path).

An example configuration file can be seen below.

Example config.yaml
# Location for reading and writing 3LC project data.
project-root-url: /home/build/.local/share/3LC/projects
# Whether to display progress bars.
display-progress: true
service:
# Port for the Object Service server.
  port: 5015
# Host address for the Object Service server.
  host: 127.0.0.1
  cache:
# Maximum size in bytes for the in-memory object cache.
    size: 1073741824
# Cache item time-to-live in seconds.
    timeout: 3600
# Enable the watch service to monitor folders for external changes.
  watch-folders: false
# Disable external self-authenticated media URLs.
  disable-external-media-urls: false
logging:
# Log level for the 3LC logger.
  level: WARNING
# Log file path for the 3LC logger.
  file: /home/build/.local/state/3LC/log/3lc.log
indexing:
# The interval between indexer scans for new objects.
  scan-interval: 10.0
# Initial debounce interval for timestamp-file writing.
  debounce-interval: 2.0
# Threshold for timestamp debouncing.
  debounce-backoff-threshold: 2
# Maximum backoff level for timestamp debouncing.
  debounce-backoff-max-level: 0
# Multiplier for timestamp debounce backoff.
  debounce-backoff-multiplier: 1.2

Configuration files¶

Resolution¶

  1. Primary configuration
    The system attempts to load configuration from:

    • The file specified by --config-file

    • The file referenced by the TLC_CONFIG_FILE environment variable

    • A default, platform-dependent configuration file

  2. Project root configuration
    After the primary configuration, if config.3lc.yaml exists in the project root (the location set by project_root_url / TLC_PROJECT_ROOT_URL), it will be loaded and merged with the current configuration.

Disabling configuration file reading

  • If --no-config-file is specified on the command line or TLC_CONFIG_FILE is set to an empty string, no configuration files are considered.

Default/project aliases¶

To make sharing of projects and results easier the system supports a special type of partial configuration file that can be used to persist default values for project aliases. These files must adhere to the following rules:

  • Naming: The files must be named default_aliases.3lc.yaml.

  • Content: The files may only contain only the aliases option. For further details, refer to the module documentation.

  • Location: The files must be placed inside a project or scan folder:

    • <PROJECT_SCAN_URL>/project-a/default_aliases.3lc.yaml # project aliases

    • <EXTRA_XXX_SCAN_URL>/default_aliases.3lc.yaml # default aliases for single folder

Project alias configuration files are read by the indexing system and will be reloaded when changed.

Overriding configuration options¶

3LC follows the following precedence rules for configuration:

api-call > command-line argument > environment variable > configuration file

The rules above should be straightforward when launching the Object Service from the command line, but it is more complicated when importing the tlc package in a Jupyter notebook (e.g. import tlc). Importing tlc causes the default configuration file to be read, and it is too late to modify these options after the module has been imported.

For this reason, there exists a tlcconfig-module that allows for creating and modifying an ConfigStore-instance prior to importing the main tlc-module. See the module documentation for an example of how to use this module.