yavadmin/ledgr-api repository overview

Ledgrr — FastAPI backend (auth, accounts, transactions, budgets, AI, Plaid) for the Ledgrr app.

⁠Ledgrr API

ledgr-api is the FastAPI backend for Ledgrr⁠ — an AI-native, self-hostable personal-finance manager where you own your data.

It handles authentication, workspaces, per-resource RBAC, accounts & net worth, transactions (categorize / split / tag / transfer), CSV/OFX/QFX import with dedupe, the deterministic rules engine, budgets, recurring detection, goals, notifications, the pluggable AI categorization pipeline, and the super-admin-gated Plaid bank sync.

⁠Tags

⁠What's inside

• Python 3.12 + FastAPI + SQLAlchemy 2.x (async)
• Alembic migrations
• uv for dependency management
• Pluggable DB dialect — asyncpg (PostgreSQL), asyncmy (MySQL), aioodbc + msodbcsql18 (SQL Server)
• Pluggable object storage (MinIO / AWS S3 / R2 / B2 / Azure Blob) via app.core.storage
• Pluggable AI provider (Anthropic Claude / OpenAI / DeepSeek / Ollama / OpenAI-compatible)
• Plaid bank-sync integration (admin-gated)

This image also runs the Arq worker process (categorization, import post-processing, Plaid sync, scheduled scans). Platform: linux/amd64.

⁠Quick start

This image is designed to run as part of the Ledgrr stack — it needs PostgreSQL, Redis, object storage, and the ledgr-nginx ingress. Use the project's docker-compose.prod.yml:

git clone https://github.com/YavLabs/ledgrr.git
cd ledgrr
cp .env.example .env
# edit .env — set APP_BASE_URL, JWT_SECRET, SETTINGS_ENC_KEY, SUPERADMIN_*, DB + storage creds
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml exec api uv run alembic upgrade head

The migration step is not optional on an upgrade, and it is not run for you. The app comes up, notices the database is behind, logs which revisions are pending, and waits — it will not half-create the schema underneath a migration that is about to create the same table. A fresh database needs no migration step: the app builds the schema on first boot and records it as current.

There is also yavadmin/ledgrr-app, which carries this image, the web UI and nginx in one container, for single-host deployments.

⁠Environment

All configuration is via the project .env. Required:

• APP_BASE_URL — the public origin (drives emails, OAuth, CORS, Plaid webhook)
• DATABASE_DIALECT + DATABASE_* (or the bundled Postgres)
• MINIO_* / STORAGE_* (or the bundled MinIO)
• JWT_SECRET
• SETTINGS_ENC_KEY — encrypts admin-managed secrets at rest
• SUPERADMIN_EMAIL, SUPERADMIN_PASSWORD

Runtime secrets — SMTP, AI provider key, Plaid client_id/secret — are configured in the admin UI and stored encrypted (not in .env).

See .env.example⁠ for the full list.

⁠Links

• Source: https://github.com/YavLabs/ledgrr⁠
• Web image: https://hub.docker.com/r/yavadmin/ledgr-web⁠
• Nginx image: https://hub.docker.com/r/yavadmin/ledgr-nginx⁠
• Deployment guide: https://github.com/YavLabs/ledgrr/blob/main/DEPLOY.md⁠