Static Configuration¶

These options are set in config.yaml and/or environment variables. They require a restart to change.

Configuration Sources¶

Configuration values are loaded in the following order (later sources override earlier ones):

Default values - Built-in defaults
YAML config file - Values from config.yaml
Environment variables - Override any value from the config file

Config File Location¶

LightHouse will search for the config file at startup at different locations, the first file that is found will be used. Supported locations are:

config.yaml
config/config.yaml
/config/config.yaml
/lighthouse/config/config.yaml
/lighthouse/config.yaml
/data/config/config.yaml
/data/config.yaml
/etc/lighthouse/config.yaml

You can also specify the config file path via the LH_CONFIG_FILE environment variable:

export LH_CONFIG_FILE=/path/to/config.yaml

Environment Variables¶

All configuration options can be set via environment variables with the LH_ prefix. Environment variables override values from the YAML config file.

Naming Convention¶

Environment variable names are derived from the YAML path by:

Adding the LH_ prefix
Converting to UPPERCASE
Replacing dots/nesting with underscores

For example:

YAML Path	Environment Variable
`entity_id`	`LH_ENTITY_ID`
`server.port`	`LH_SERVER_PORT`
`server.tls.enabled`	`LH_SERVER_TLS_ENABLED`
`storage.dsn`	`LH_STORAGE_DSN`
`logging.internal.level`	`LH_LOGGING_INTERNAL_LEVEL`

Special Environment Variables¶

Variable	Description
`LH_CONFIG_FILE`	Path to the configuration file
`LH_LOG_LEVEL`	Shortcut for `LH_LOGGING_INTERNAL_LEVEL`

Array/List Values¶

For configuration options that accept lists (e.g., trusted_proxies), use comma-separated values:

export LH_SERVER_TRUSTED_PROXIES="10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"

YAML-Only Options¶

Some complex configuration options can only be set via YAML (not environment variables):

signing.filesystem - Filesystem KMS configuration
signing.pkcs11 - PKCS#11 HSM configuration

Example: Docker/Kubernetes Deployment¶

Environment variables are particularly useful for container deployments:

# docker-compose.yml
services:
  lighthouse:
    image: lighthouse:latest
    environment:
      - LH_ENTITY_ID=https://ta.example.com
      - LH_SERVER_PORT=8080
      - LH_STORAGE_DRIVER=postgres
      - LH_STORAGE_DSN=host=db user=lighthouse password=secret dbname=lighthouse
      - LH_LOG_LEVEL=INFO
    volumes:
      - ./keys:/keys

`entity_id`¶

URI required LH_ENTITY_ID

The entity_id option sets the Entity Identifier for this federation entity. This is a URI that uniquely identifies your entity within the federation and is used as the iss and sub claims in the Entity Configuration JWT.

The entity ID is typically the base URL where your federation endpoints are served.

config.yaml

entity_id: "https://ta.example.com"

Required

This option is required. LightHouse will fail to start if entity_id is not specified.

Moved from federation_data

This option was previously located at federation_data.entity_id. It has been moved to a top-level configuration option. Use lhmigrate config to automatically update your config file.

Example Config File¶

The following is an example config.yaml file: