config.sqlite.yaml

# Codex Configuration with SQLite

# Base Data Directory
# ===================
# All sub-directories (thumbnails, uploads, plugins, cache, SQLite DB) derive from this path
# unless explicitly overridden. Override: CODEX_DATA_DIR
# data_dir: data

database:
  db_type: sqlite
  sqlite:
    path: ./data/codex.db
    pragmas:
      journal_mode: WAL
      synchronous: NORMAL
      # Note: foreign_keys is ALWAYS ON for data integrity (cannot be disabled)
    # Connection Pool Settings (optional - defaults shown)
    # max_connections: 16
    # min_connections: 2
    # acquire_timeout_seconds: 30
    # idle_timeout_seconds: 300
    # max_lifetime_seconds: 1800
    # operation_deadline_seconds: 30

application:
  host: 127.0.0.1
  port: 8080
  # base_url: https://codex.example.com  # Public-facing URL (used for OIDC redirects, email links)

logging:
  level: info
  console: true
  # file: ./logs/codex.log  # Uncomment to enable file logging

# Auth config - uses defaults, override with CODEX_AUTH_* env vars
# Defaults: JWT 24h expiry, Argon2 (19456, 2, 1)
auth:
  jwt_secret: "CHANGE_ME_IN_PRODUCTION" # Override with CODEX_AUTH_JWT_SECRET env var
  # jwt_expiry_hours: 24
  # refresh_token_enabled: true
  # refresh_token_expiry_days: 30
  # email_confirmation_required: false
  # argon2_memory_cost: 19456
  # argon2_time_cost: 2
  # argon2_parallelism: 1
  # OIDC / SSO Authentication (disabled by default)
  # oidc:
  #   enabled: true
  #   auto_create_users: true       # Auto-create local users on first OIDC login
  #   default_role: reader           # Default role when no group mapping matches (admin, maintainer, reader)
  #   redirect_uri_base: "https://codex.example.com" # Optional, defaults to http://{application.host}:{application.port}
  #   providers:
  #     authentik:                   # Provider key (used in URLs: /auth/oidc/authentik/login)
  #       display_name: "Authentik SSO"
  #       issuer_url: "https://authentik.example.com/application/o/codex/"
  #       client_id: "codex-client-id"
  #       client_secret: "codex-client-secret"     # Or use client_secret_env below
  #       # client_secret_env: "OIDC_AUTHENTIK_SECRET"  # Read secret from env var instead
  #       scopes:
  #         - profile
  #         - email
  #       # Claim mappings (defaults shown)
  #       # groups_claim: groups
  #       # username_claim: preferred_username
  #       # email_claim: email
  #       # Group-to-role mapping (optional)
  #       # role_mapping:
  #       #   admin:
  #       #     - codex-admins
  #       #   maintainer:
  #       #     - codex-editors
  #       #   reader:
  #       #     - codex-users

# API config - all fields use defaults
# Defaults: enable_api_docs=false, api_docs_path="/docs", cors_enabled=true, max_page_size=100
# Uncomment below to enable API docs (Scalar):
# api:
#   base_path: /api/v1
#   enable_api_docs: true
#   api_docs_path: /docs
#   cors_enabled: true
#   cors_origins:
#     - "*"
#   max_page_size: 100

# Email Settings (optional - for email verification)
# email:
#   smtp_host: localhost
#   smtp_port: 587
#   smtp_username: ""
#   smtp_password: ""
#   smtp_from_email: noreply@example.com
#   smtp_from_name: Codex
#   verification_token_expiry_hours: 24
#   verification_url_base: https://codex.example.com  # Falls back to application.base_url

# Task Worker Settings (Startup-Time - Require Restart)
# ======================================================
# These settings control worker behavior and require a restart to take effect.
task:
  worker_count: 2 # Number of parallel task workers (override: CODEX_TASK_WORKER_COUNT)

# Scanner Settings (Startup-Time - Require Restart)
# ==================================================
scanner:
  max_concurrent_scans: 2 # Max concurrent library scans (override: CODEX_SCANNER_MAX_CONCURRENT_SCANS)

# Scheduler Settings (Startup-Time - Require Restart)
# ====================================================
# Controls the timezone for all cron-based scheduled tasks (library scans,
# deduplication, thumbnail generation, etc.).
# scheduler:
#   timezone: UTC  # IANA timezone (override: CODEX_SCHEDULER_TIMEZONE)

# Files Settings (Startup-Time - Require Restart)
# ================================================
# Directory paths for thumbnails, user uploads, and plugin data.
# These default to {data_dir}/{subdir} and can be individually overridden.
files:
  thumbnail_dir: data/thumbnails # Thumbnail cache directory (override: CODEX_FILES_THUMBNAIL_DIR)
  uploads_dir: data/uploads # User uploads directory (override: CODEX_FILES_UPLOADS_DIR)
  plugins_dir: data/plugins # Plugin file storage directory (override: CODEX_FILES_PLUGINS_DIR)

# PDF Rendering Settings
# ======================
# pdf:
#   pdfium_library_path: null  # Path to PDFium library (optional, auto-detected)
#   render_dpi: 150            # Default render DPI (72-300)
#   jpeg_quality: 85           # JPEG quality for rendered pages (1-100)
#   cache_rendered_pages: true # Enable rendered page caching
#   cache_dir: data/cache      # Directory for caching rendered PDF pages

# PDF Handle Cache (in-memory open-document cache, separate from the disk page cache)
# ===================================================================================
# pdf_handle_cache:
#   enabled: true              # Master switch (when false, every render re-opens the PDF)
#   capacity: 256              # Max resident open handles (memory ~ capacity * 5-15 MB)
#   idle_ttl_minutes: 15       # Drop a handle after this many minutes of inactivity
#   sweep_interval_seconds: 60 # Background sweeper period for enforcing idle_ttl_minutes

# Komga-Compatible API (disabled by default)
# ==========================================
# Enables third-party apps like Komic to connect using Komga API format
# komga_api:
#   enabled: false
#   prefix: komga  # URL prefix: /{prefix}/api/v1/...

# Rate Limiting (enabled by default)
# ==================================
# Protects API endpoints from abuse using token bucket algorithm
# rate_limit:
#   enabled: true
#   anonymous_rps: 10          # Requests/second for anonymous users
#   anonymous_burst: 50        # Burst size for anonymous users
#   authenticated_rps: 50      # Requests/second for authenticated users
#   authenticated_burst: 200   # Burst size for authenticated users
#   exempt_paths:              # Glob patterns for paths exempt from rate limiting
#     - /health
#     - /api/v1/events
#     - /api/v1/events/**
#     - /api/v1/books/*/thumbnail   # Exempt book thumbnails
#   cleanup_interval_secs: 60  # How often to clean up stale buckets
#   bucket_ttl_secs: 300       # Time before a bucket is considered stale

# OpenTelemetry observability (disabled by default).
#
# Uncomment and point `otlp.endpoint` at your collector to enable trace and
# metric export. See docs/docs/observability.md for the schema, backend matrix
# (SigNoz, Tempo, Honeycomb, Uptrace, ...), and sampling guidance.
# observability:
#   enabled: true
#   service_name: codex
#   otlp:
#     endpoint: http://localhost:4317   # e.g. a local Jaeger or your operator's collector
#     protocol: grpc                    # grpc | http/protobuf | http/json
#     # headers:                        # auth/tenant headers (e.g. signoz-access-token)
#     #   x-honeycomb-team: ...
#     timeout_ms: 5000
#     # Optional override for the browser RUM proxy, which always speaks
#     # OTLP/HTTP. Set this when `endpoint` uses gRPC (e.g. Jaeger 4317) so
#     # browser spans hit the matching HTTP port (e.g. 4318). Falls back to
#     # `endpoint` when unset.
#     # proxy_endpoint: http://localhost:4318
#   traces:
#     enabled: true
#     sample_ratio: 1.0                 # tune down on busy deployments
#   metrics:
#     enabled: true
#     export_interval_ms: 30000
#   browser:
#     enabled: false                    # opt-in browser RUM, proxied through codex
#     proxy_path: /api/v1/observability/otlp
#     sample_ratio: 0.1