An advanced finance tracker.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

LenoreFin began as a simple Excel spreadsheet I used to manage my family's budget. But over time, I realized no existing tools gave me the control, flexibility, and privacy I wanted. So I built LenoreFin—a personal finance tracker that puts you in charge.

Designed for self-hosting, LenoreFin keeps your financial data completely local, with no third-party syncing or hidden services.

Key features:

• Account tracking — checking, savings, credit cards, investments, and loans with real-time balance forecasting
• Transaction management — full CRUD, bulk editing, CSV import, file attachments, and tag-based categorization
• Credit card tools — statement cycle tracking, due dates, minimum payment calculation, rewards tracking
• Investment return estimation — Modified Dietz annualized return calculated from transaction history; apply directly to APY forecast
• Budgeting & planning — tag-based budgets, savings goal tracking
• Recurring detection — automatic detection of recurring payments with one-click reminder creation
• Bill reminders — recurring reminder engine with customizable repeat schedules
• Custom reports — totals and year-over-year comparison reports, filterable by account, tag, and status; scheduled execution with history
• Logging & diagnostics — structured log viewer with level filtering and downloadable log bundle
• Push notifications — browser Web Push for new inbox messages (VAPID, opt-in)
• PWA / offline mode — installable as a PWA; read-only access and graceful degradation when offline
• Multi-user auth — Full Access and Readonly permission groups
• Self-hosted — single Docker image, no telemetry, no third-party data sharing

(back to top)

Built With

• 
• 
• 

(back to top)

Getting Started

Welcome to LenoreFin! This guide will help you set up and run the application using Docker and Docker Compose.

Prerequisites

Make sure you have the following installed on your system:

• Docker
• Docker Compose

Step 1: Create a .env File

Create a .env file in the root directory of the project. This file will store environment variables required to run the application. Below is an example of the variables you need to define:

DEBUG=0
SECRET_KEY=mysupersecretkey
DJANGO_ALLOWED_HOSTS=localhost
CSRF_TRUSTED_ORIGINS=http://localhost
SQL_ENGINE=django.db.backends.postgresql
SQL_DATABASE=lenorefin
SQL_USER=lenorefinuser
SQL_PASSWORD=somepassword
SQL_HOST=db
SQL_PORT=5432
DATABASE=postgres
DJANGO_SUPERUSER_PASSWORD=supervisorpassword
DJANGO_SUPERUSER_EMAIL=someone@somewhere.com
DJANGO_SUPERUSER_USERNAME=supervisor
VITE_API_KEY=someapikey
TIMEZONE=America/New_York

Adjust these values according to your environment and application requirements.

Step 2: Create a docker-compose.yml File

As of v1.4, LenoreFin uses a single consolidated container image (novanglus96/lenorefin) that bundles the frontend, backend, nginx, and worker together. You only need three services:

services:
  app:
    image: novanglus96/lenorefin:latest
    container_name: lenorefin
    command: /home/app/web/start.app.sh
    volumes:
      - lenorefin_static:/home/app/web/staticfiles
      - lenorefin_media:/home/app/web/mediafiles
      - lenorefin_bkp:/backups/
    ports:
      - "8080:80"
    depends_on:
      - db
      - redis
    networks:
      - lenorefin
    env_file:
      - ./.env
    environment:
      - DEBUG=0

  db:
    image: postgres:15
    container_name: lenorefin_db
    volumes:
      - lenorefin_postgres:/var/lib/postgresql/data/
      - lenorefin_bkp:/backups/
    networks:
      - lenorefin
    env_file:
      - ./.env
    environment:
      - TZ=UTC
      - POSTGRES_USER=${SQL_USER}
      - POSTGRES_PASSWORD=${SQL_PASSWORD}
      - POSTGRES_DB=${SQL_DATABASE}

  redis:
    image: redis:7-alpine
    container_name: lenorefin_redis
    command: ["redis-server", "--appendonly", "yes"]
    networks:
      - lenorefin
    restart: unless-stopped

networks:
  lenorefin:

volumes:
  lenorefin_postgres:
  lenorefin_static:
  lenorefin_media:
  lenorefin_bkp:

Step 3: Run the Application

1. Start the services:

   docker compose up -d

2. Access the application in your browser at http://localhost:8080.

Notes

• Adjust the port (8080:80) as needed for your environment.
• If you encounter any issues, ensure your .env file has the correct values and your Docker and Docker Compose installations are up to date.

Enjoy using LenoreFin!

(back to top)

---

Migrating from pre-v1.4 to v1.4

Version 1.4 consolidates the previous multi-container setup (separate frontend, backend, worker, and nginx containers) into a single app container. Follow these steps to migrate an existing installation.

1. Back up your database

Before making any changes, export your data:

docker exec lenorefin_backend python manage.py export_user_data

Copy the backup out of the container to a safe location.

2. Stop and remove old containers

docker compose down

3. Update your docker-compose.yml

Replace your existing docker-compose.yml with the new 3-service format shown in Step 2 above. The old frontend, backend, worker, and nginx services are no longer needed.

4. Update your .env file

5. Rename volumes (if using named volumes from the old setup)

The old setup used volumes named lenorefin_static_volume, lenorefin_media_volume, and lenorefin_postgres_data. The new setup uses lenorefin_static, lenorefin_media, and lenorefin_postgres.

If you have existing data you want to preserve, copy it between volumes before starting:

# Example: migrate postgres data
docker run --rm \
  -v lenorefin_postgres_data:/from \
  -v lenorefin_postgres:/to \
  alpine sh -c "cp -av /from/. /to/"

Repeat for lenorefin_static_volume → lenorefin_static and lenorefin_media_volume → lenorefin_media if needed.

Alternatively, use the backup/restore feature: restore your data export after the new stack is running via the Backup & Restore page in the app.

6. Pull and start the new image

docker compose pull
docker compose up -d

7. Verify

Open the app in your browser. Check the Admin → Version page to confirm you are on v1.4+.

Usage

See the full documentation.

(back to top)

Roadmap

Shipped in v1.4

• Django 5.2 LTS migration
• Consolidated single-container deployment (nginx + gunicorn + worker in one image)
• Parent accounts (combined balance view across child accounts)
• Interest earned on savings / investment accounts
• Custom report builder (totals & year-over-year comparison)
• File attachments on transactions
• Backup & restore system
• PWA packaging + offline read-only mode
• Multi-user auth (Full Access / Readonly groups)
• Structured log viewer with bundle download
• Bank logos on account header and navigation
• Transaction filtering (search, status, type, tag, date range)

Planned

• Scheduled reports (run a saved report on a schedule, deliver to inbox)
• WebSocket real-time sync (live updates across multiple connected clients)
• Vuetify 4 migration (planned for later 2026)

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. Please follow these steps and guidelines to help us maintain a smooth development process.

1. Fork the Repository

• Click the Fork button at the top-right of this repository to create your own copy.
• Clone your fork locally.

2. Branch Naming

Create branches following this pattern:

• Features: feature/branch-name - For new features or enhancements.
• Fixes: fix/branch-name - For bug fixes or patches.

3. Pull Request Targets

Submit pull requests to the appropriate branch based on the stability of your changes:

Target Branch	Purpose
main	Production-ready changes for release.
rc	Release candidates for staging releases.
alpha	Experimental and unstable changes.
beta	More stable than alpha, for broader testing.

PRs to main and rc branches are for finalized changes intended for the next release. PRs to alpha and beta are for testing and experimental work.

4. Commit Message Format

We use semantic commit messages to automate changelog and versioning.

Format:

<type>(optional scope): <short description>

Common types
feat:	A new feature
fix:	A bug fix
chore:	Changes to build process or auxiliary tools
docs:	Documentation only
style:	Formatting, missing semicolons, etc; no code change
refactor:	Code change that neither fixes a bug nor adds a feature
perf:	Performance improvements
test:	Adding or fixing tests

Breaking changes: Add ! after type or scope

feat!: drop support for Node 10
fix(api)!: change endpoint response format

Examples:

• feat: add user profile page
• fix(auth): handle expired tokens gracefully
• chore: update dependencies
• perf: optimize image loading

5. Pull Request Checklist

Before submitting your PR, please ensure:

• Your branch is up to date with the target branch.
• Your code passes all tests and linters.
• You have added or updated tests if applicable.
• Relevant documentation has been added or updated.
• Your PR description clearly explains your changes and references related issues.

6. Testing Changes

Please test your changes locally or in a staging environment before opening a PR. Use alpha or beta branches for testing experimental changes.

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Support

Or

Contact

John Adams - Lenore.Apps@gmail.com

Project Link: https://github.com/Novanglus96/LenoreFin

(back to top)

Acknowledgements

A heartfelt thanks to our Patrons for their generous support! Your contributions help us maintain and improve this project.

⭐ Thank You to Our Supporters:

Want to see your name here? Support us on Patreon to join our amazing community and shape the future of LenoreFin!

(back to top)