Skip to content

Installation

LightningROD runs as a Docker Compose stack with two services: the web application and PostgreSQL.

Requirements

  • Docker and Docker Compose
  • A CSV export of your charging history (optional, for seeding data)

Docker Compose

git clone https://github.com/yourusername/LightningROD.git
cd LightningROD
cp .env.example .env

Edit .env to set a real password:

.env
POSTGRES_USER=lightningrod
POSTGRES_PASSWORD=your-secure-password  # (1)!
POSTGRES_DB=lightningrod
POSTGRES_HOST=localhost
APP_PORT=8000
DEBUG=false
  1. Change this from the default changeme before running in production.

Start the stack:

docker compose up --build -d

If you're running behind a reverse proxy (Traefik, nginx, Caddy), you may want to remove the port mapping and configure your proxy to route to the container directly.

docker compose up --build -d

Point your proxy at the web service on port 8000.

The app will be available at http://localhost:8000 (or your configured APP_PORT).

What Happens on Startup

The container's entrypoint script handles setup automatically:

entrypoint.sh
#!/bin/bash
set -e

echo "Running Alembic migrations..."
uv run alembic upgrade head

echo "Starting LightningROD..."
exec uv run uvicorn web.main:app --host 0.0.0.0 --port 8000
  1. Alembic runs all pending database migrations
  2. Uvicorn starts the FastAPI application

Note

The web service waits for PostgreSQL to pass its health check before starting. If the database is slow to initialize on first run, the web container will retry until it's ready.

Verify It's Running

docker compose ps

You should see both db and web services running. Open http://localhost:8000 in your browser.

The database starts empty. See Data Import to load your charging history.

Stopping and Restarting

# Stop
docker compose down

# Restart
docker compose up -d

Your data is stored in a named Docker volume (pgdata) and persists across restarts and rebuilds.

Updating

git pull
docker compose up --build -d

Migrations run automatically on startup, so schema changes are applied when you update.