Skip to content

Configuration

LightningROD is configured through environment variables and in-app settings.

Environment Variables

Variable Default Description
POSTGRES_USER lightningrod PostgreSQL username
POSTGRES_PASSWORD changeme PostgreSQL password
POSTGRES_DB lightningrod Database name
POSTGRES_HOST localhost Database host. Set to db when using Docker Compose (handled automatically).
APP_PORT 8000 Port the web UI is served on
DEBUG false Enable debug logging and SQL echo

Example

.env.example
# ─── Which fields do I need? ───────────────────────────────────────────────
# Default Postgres (docker compose up, Unraid Compose Manager):  POSTGRES_* + APP_*
# Standalone SQLite (docker/docker-compose.standalone.yml):      APP_* only
# Custom deploy (bare `docker run`, external DB, etc):           DATABASE_URL + APP_*

# ─── Postgres credentials ──────────────────────────────────────────────────
# Used by the default compose stack to provision the `db` container AND
# interpolated into DATABASE_URL on the `web` service. 
# Update Credentials
POSTGRES_USER=lightningrod
POSTGRES_PASSWORD=changeme
POSTGRES_DB=lightningrod

# ─── Application (all deployments) ─────────────────────────────────────────
# Host port the `web` container is published on
APP_PORT=8000

# Toggles verbose logging / debug behaviors.
APP_DEBUG=false

# Demo / read-only mode. When 'true':
#   - blocks DELETE/PUT/PATCH requests and renders a banner
#   - on SQLite backends, re-seeds a fresh demo DB on first boot
# Set to 'false' to run against your real data.
DEMO_MODE=false

# ─── Image versioning (local builds only) ──────────────────────────────────
# Tag applied to the built image (`lightningrod-web:<tag>`). 
# Ignored when pulling the prebuilt image from GHCR.
LIGHTNINGROD_VERSION=dev

# ─── DATABASE_URL (custom deploys only) ────────────────────────────────────
# Skip this for the default Postgres stack and the standalone SQLite stack
# Both compose files set DATABASE_URL automatically.
#
# Set it here only if you are running the app outside those compose files
#
# IMPORTANT: Postgres URLs must use the asyncpg driver scheme.
# Plan 'postgresql://' URL will crash on startup looking for psycopg2
#
# DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname
# DATABASE_URL=sqlite+aiosqlite:////absolute/path/to/lightningrod.db

Warning

Change POSTGRES_PASSWORD from the default before running in production. The default value changeme is only suitable for local development.

How Configuration is Loaded

The application uses pydantic-settings to read environment variables. The configuration class assembles the async database URL from the individual PostgreSQL variables:

config.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
"""Environment-backed application settings."""

from typing import Any, cast

from pydantic import AliasChoices, Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

    database_url: str
    app_port: int = 8000
    debug: bool = Field(
        default=False,
        validation_alias=AliasChoices("APP_DEBUG", "LIGHTNINGROD_DEBUG"),
    )


settings = Settings.model_validate(cast(dict[str, Any], {}))

Docker Compose Override

When running with Docker Compose, the POSTGRES_HOST is automatically set to db (the service name) via the environment section in docker-compose.yml:

docker-compose.yml
  web:
    build:
      context: .
      dockerfile: docker/Dockerfile
    env_file: .env
    environment:
      - POSTGRES_HOST=db

You do not need to change POSTGRES_HOST in your .env file when using Docker Compose.

In-App Settings

Settings configured through the web UI at /settings:

Setting Storage Description
Vehicles ev_vehicles table Vehicle profiles, active vehicle selection, ICE comparison inputs
Charging networks ev_charging_networks table Per-network electricity costs and colors
Locations ev_location_lookup table Named locations with optional cost override
Charger stalls ev_charger_stalls table Charger specs per location
Network subscriptions ev_network_subscriptions table Member rate windows and monthly fees for network plans
Gas price history gas_price_history table Monthly station and average gas prices for savings ranges
Unit preferences app_settings US (mi/kWh) or EU (km/kWh)
Timezone app_settings Display timezone (e.g., America/New_York)
Comparison toggles app_settings Show or hide cost comparison sections
Gas price sensor IDs app_settings HA entity IDs used for gas price ingestion
HA URL app_settings Home Assistant instance URL
HA Access Token app_settings Long-lived access token for HA WebSocket
HA VIN Override app_settings Override auto-detected vehicle VIN
HA Unit System app_settings Auto-detect, metric, or imperial
HA Auto-connect app_settings Connect to HA automatically on startup

These are managed at /settings and stored in the database.