Configuration#

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

All the options are documented in the tlcconfig.options module. The documentation for each option details the configuration file key, environment variable and command-line argument to the 3LC Object Service that can be used to set the option.

Due to 3LC’s architecture, where multiple processes are involved (the 3LC Object Service, Jupyter Notebooks, and the 3LC Dashboard run as distinct processes), there are some caveats to be aware of when configuring 3LC.

The preferred way of configuring 3LC is through the 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.

This file is created, with default values, the first time 3LC is launched (either when starting the Object Service, or when invoking import tlc in a notebook). An example configuration file can be seen below.

Example config.yaml
# Configuration file for 3LC.AI
#
# This YAML file contains setting for the tlc Python Package.
# Created at 2023-11-01 19:57:06

# Aliases Settings
aliases:                                          # List of aliases.
  TEST_DATA: /location/of/test/data               # Alias for test data.

# Service Settings
service:

  port: 5015                                      # Port for the server.
  dashboard: false                                # None
  host: 127.0.0.1                                 # Host for the server.

  # Specify license or license file
  #  
  # The option can be either be the license key or point to a local file contai
  license:

# Indexing Settings
indexing:

  # Location for reading and writing 3LC data.
  #  
  # This option is mandatory and must point to a location (e.g. directory on disk or
  # object store bucket) with write access. The location will be created if it does not exist.
  #
  # If the option value contains an environment variable, it will be expanded.
  project-root-url: $HOME/.local/share/3LC/projects

  # Locations to scan for 3LC objects (runs and tables). 
  # Usually a 'projects' directory containing multiple projects, but can also be a single project folder.
  project-scan-urls:
    - /path/to/my/projects
    - s3://bucket/path/to/projects

# Logging Settings
logging:

  # Log file for the 3LC logger.
  #  
  # The directory will be created if it does not exist.
  #  
  # If the option value contains an environment variable, it will be expanded.
  logfile: $HOME/.local/share/3LC/Logs\3LC.log

  # Log level for the 3LC logger.
  #  
  # This is a string corresponds to the standard Python logging levels:
  #   - DEBUG
  #   - INFO
  #   - WARNING
  #   - ERROR
  #   - CRITICAL
  loglevel: INFO

# Tlc Settings
tlc:

  # Whether to display progress bars or not.
  #  
  # The option can be either 0 or 1, where 0 means no progress bars and 1 means
  display-progress: 1

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, 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 OptionLoader-instance prior to importing the main tlc-module. See the module documentation for an example of how to use this module.