Skip to content
Logchef

Configuration

LogChef uses a minimal TOML configuration file for bootstrap settings, with runtime configuration managed through the Admin Settings UI. This guide explains the essential configuration options and how to manage non-essential settings through the web interface.

Configuration Architecture

LogChef separates configuration into two categories:

Essential (Bootstrap) Settings - Required in config.toml:

  • Server connection details (port, host)
  • SQLite database path
  • OIDC authentication credentials
  • Admin user emails and API token secrets
  • Logging configuration

Runtime Settings - Managed via Admin Settings UI:

  • Alerting configuration (Alertmanager URL, intervals, timeouts)
  • AI/LLM settings (API keys, models, endpoints)
  • Session management (duration, concurrency)
  • Frontend URL for CORS

On first boot, LogChef seeds the database with values from config.toml. After that, runtime settings are stored in the database and managed through the Admin Settings UI at Administration → System Settings.

Essential Configuration

These settings must be present in config.toml for LogChef to start:

Server Settings

Configure the HTTP server and frontend settings:

[server]
# Port for the HTTP server (default: 8125)
port = 8125


# Host address to bind to (default: "0.0.0.0")
host = "0.0.0.0"


# URL of the frontend application
# Leave empty in production, used only in development
frontend_url = ""


# HTTP server timeout for requests (default: 30s)
http_server_timeout = "30s"

Database Configuration

SQLite database settings for storing metadata:

[sqlite]
# Path to the SQLite database file
path = "logchef.db"

Authentication

OpenID Connect (OIDC)

Configure your SSO provider (example using Dex):

[oidc]
# URL of your OIDC provider
provider_url = "http://dex:5556/dex"


# Authentication endpoint URL (Optional: often discovered via provider_url)
auth_url = "http://dex:5556/dex/auth"


# Token endpoint URL (Optional: often discovered via provider_url)
token_url = "http://dex:5556/dex/token"


# OIDC client credentials
client_id = "logchef"
client_secret = "logchef-secret"


# Callback URL for OIDC authentication
# Must match the URL configured in your OIDC provider
redirect_url = "http://localhost:8125/api/v1/auth/callback"


# Required OIDC scopes
scopes = ["openid", "email", "profile"]

Auth Settings

Configure authentication behavior:

[auth]
# List of email addresses that have admin privileges (required)
admin_emails = ["admin@corp.internal"]


# Secret key for API token hashing (required, min 32 characters)
# Generate with: openssl rand -hex 32
api_token_secret = "your-secret-key-minimum-32-characters-long"

Note: Session duration, concurrent session limits, and default token expiry are managed via the Admin Settings UI under Authentication settings.

Logging

Configure application logging:

[logging]
# Log level: "debug", "info", "warn", "error"
level = "info"

Runtime Configuration (Admin Settings UI)

The following settings are managed through the web interface at Administration → System Settings after first boot. You can optionally set initial values in config.toml which will be seeded to the database on first boot.

AI SQL Generation

Configure AI-powered SQL generation through the Admin Settings UI:

Settings available:

  • Enabled: Enable/disable AI features
  • API Key: OpenAI API key (marked as sensitive, hidden in UI)
  • Base URL: OpenAI-compatible API endpoint (default: https://api.openai.com/v1)
  • Model: Model name (e.g., “gpt-4o”, “gpt-4o-mini”)
  • Max Tokens: Maximum tokens to generate (default: 1024)
  • Temperature: Generation temperature 0.0-1.0 (default: 0.1)

Supported Providers:

Optional config.toml seeding (first boot only):

[ai]
enabled = false
base_url = "https://api.openai.com/v1"
api_key = ""  # Set via Admin UI after first boot
model = "gpt-4o"
max_tokens = 1024
temperature = 0.1

Note: After first boot, changes to [ai] section in config.toml are ignored. Manage settings via the UI.

Alerting

Configure real-time log monitoring with Alertmanager integration through the Admin Settings UI.

Settings available:

  • Enabled: Enable/disable alert evaluation and delivery
  • Alertmanager URL: Prometheus Alertmanager endpoint
    • Supports HTTP Basic Auth: https://username:password@alertmanager.example.com
    • Includes health check button to test connectivity
  • Evaluation Interval: How often to check all active alerts (e.g., “1m”)
  • Default Lookback: Default time range for alert queries (e.g., “5m”)
  • History Limit: Number of historical events to keep per alert (default: 50)
  • External URL: Backend URL for API access
  • Frontend URL: Frontend URL for web UI links in notifications
  • Request Timeout: Alertmanager HTTP request timeout (default: “5s”)
  • TLS Insecure Skip Verify: Skip TLS cert verification (dev only)

Optional config.toml seeding (first boot only):

[alerts]
enabled = false
evaluation_interval = "1m"
default_lookback = "5m"
history_limit = 50
alertmanager_url = ""
external_url = ""
frontend_url = ""
request_timeout = "5s"
tls_insecure_skip_verify = false

Note: After first boot, manage all alert settings via Administration → System Settings → Alerts. The health check button allows you to test Alertmanager connectivity before saving.

For alert configuration examples, notification setup, and best practices, see the alerting feature guide.

Environment Variables

All configuration options set in the TOML file can be overridden or supplied via environment variables. This is particularly useful for sensitive information like API keys or for containerized deployments.

Environment variables are prefixed with LOGCHEF_. For nested keys in the TOML structure, use a double underscore __ to represent the nesting.

Format: LOGCHEF_SECTION__KEY=value

Examples:

  • Set server port:
    Terminal window
    export LOGCHEF_SERVER__PORT=8125
  • Set OIDC provider URL:
    Terminal window
    export LOGCHEF_OIDC__PROVIDER_URL="http://dex.example.com/dex"
  • Set admin emails (comma-separated for arrays):
    Terminal window
    export LOGCHEF_AUTH__ADMIN_EMAILS="admin@example.com,ops@example.com"
  • Set AI API Key:
    Terminal window
    export LOGCHEF_AI__API_KEY="sk-your_actual_api_key_here"
  • Enable AI features and set the model:
    Terminal window
    export LOGCHEF_AI__ENABLED=true
    export LOGCHEF_AI__MODEL="gpt-4o"
  • Configure alerting:
    Terminal window
    export LOGCHEF_ALERTS__ENABLED=true
    export LOGCHEF_ALERTS__ALERTMANAGER_URL="http://alertmanager:9093"
    export LOGCHEF_ALERTS__FRONTEND_URL="https://logchef.example.com"

Environment variables take precedence over values defined in the TOML configuration file.

Production Configuration

For production deployments, ensure you:

  1. Set appropriate host and port values
  2. Configure a secure client_secret for OIDC
  3. Set the correct redirect_url matching your domain
  4. Configure admin emails for initial access
  5. Adjust session duration based on your security requirements
  6. Set logging level to “info” or “warn”
  7. If using AI features, ensure LOGCHEF_AI__API_KEY is set securely
  8. If using alerting, configure Alertmanager and set frontend_url for correct generator links
  9. Enable TLS for Alertmanager communication in production

Minimal Production Configuration

This example shows the essential configuration required to run LogChef. All other settings (AI, alerting, sessions) are managed via the Admin Settings UI.

[server]
port = 8125
host = "0.0.0.0"
http_server_timeout = "30s"


[sqlite]
path = "/data/logchef.db"


[oidc]
provider_url = "https://dex.example.com"
client_id = "logchef"
client_secret = "your-secure-secret"
redirect_url = "https://logchef.example.com/api/v1/auth/callback"
scopes = ["openid", "email", "profile"]


[auth]
admin_emails = ["admin@example.com"]
api_token_secret = "your-secret-key-minimum-32-characters-long"


[logging]
level = "info"

After deployment:

  1. Login as admin user
  2. Navigate to Administration → System Settings
  3. Configure:
    • AI tab: Enable AI features and add API key
    • Alerts tab: Configure Alertmanager URL and settings
    • Authentication tab: Set session duration and limits
    • Server tab: Set frontend URL if needed

See config.sample.toml for a complete minimal configuration example.