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

# PostgreSQL
POSTGRES_USER=lightningrod
POSTGRES_PASSWORD=changeme
POSTGRES_DB=lightningrod
POSTGRES_HOST=localhost

# Application
APP_PORT=8000
DEBUG=false

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
from pydantic_settings import BaseSettings, SettingsConfigDict


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

    postgres_user: str
    postgres_password: str
    postgres_db: str
    postgres_host: str = "localhost"
    app_port: int = 8000
    debug: bool = False

    @property
    def database_url(self) -> str:
        return (
            f"postgresql+asyncpg://{self.postgres_user}:"
            f"{self.postgres_password}@{self.postgres_host}/"
            f"{self.postgres_db}"
        )


settings = Settings()

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: 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
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
Gas comparison	`app_settings`	MPG and gas price for savings calculations
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
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.