ppcm/budgetos repository overview

⁠Supported Tags

• 1.5.6, 1.5, 1, latest

⁠Quick Reference

• Maintained by: PPCM⁠
• Where to get help: GitHub Issues⁠
• Where to file issues: GitHub Issues⁠
• Source: GitHub⁠
• Supported architectures: amd64, arm64

⁠What is BudgetOS?

BudgetOS is a self-hosted web application for managing personal finances. It provides a complete solution for tracking bank accounts, credit cards, transactions, and generating financial reports.

⁠Key Highlights

• Multi-user support with role-based access control
• Multi-database support (SQLite, PostgreSQL, MariaDB)
• Bank import from CSV, Excel, QIF, OFX/QFX files
• Automatic categorization with customizable rules
• Financial reports with trends, forecasts, and category breakdowns
• Multilingual interface (English, French, German, Spanish, Italian, Portuguese, Russian, Chinese)

⁠Features

⁠Core Finance

• Bank Accounts — Checking, savings, investment, and credit card accounts with color coding
• Transactions — Full CRUD with search, filters, sorting, date ranges, and expandable details
• Credit Cards — Immediate and deferred debit types with customizable billing cycles
• Recurring Transactions — Scheduled operations with multiple frequencies

⁠Import & Reconciliation

• Bank Import — CSV, Excel (.xlsx), QIF, OFX/QFX file support with smart column mapping
• Auto-Reconciliation — Duplicate detection and automatic matching
• Manual Reconciliation — Dedicated mode for reconciling against bank statements

⁠Organization

• Categories — Three-column layout (Income, Expenses, Transfers) with icons and colors
• Payees — Manage merchants and beneficiaries with logos and alias learning
• Categorization Rules — Automatic transaction classification

⁠Analytics

• Dashboard — Financial overview with balance summary and recent transactions
• Trend Reports — Income vs. expenses bar chart over 12 months
• Category Reports — Spending breakdown with donut chart
• Forecast — Cash flow projections at 30, 60, and 90 days

⁠Administration

• Multi-User — Role-based access control (Super Admin, Admin, User)
• User Management — Create, edit, suspend users
• Group Management — Organize users into groups
• System Settings — Public registration toggle, default group configuration

⁠Quick Start

⁠Using Docker (Recommended)

# Create data directory
mkdir -p budgetos-data

# Run with Docker
docker run -d \
  --name budgetos \
  -p 3000:3000 \
  -v $(pwd)/budgetos-data:/app/data \
  -e SESSION_SECRET=your-secret-key-change-me \
  ppcm/budgetos:latest

Open http://localhost:3000⁠ and create your admin account.

⁠Using Docker Compose

Create a docker-compose.yml file:

services:
  budgetos:
    image: ppcm/budgetos:latest
    container_name: budgetos
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
      - ./logs:/app/logs
    environment:
      - SESSION_SECRET=your-secret-key-change-me
      - NODE_ENV=production
    restart: unless-stopped

Then run:

docker compose up -d

⁠Environment Variables

⁠General

⁠Database

⁠PostgreSQL (when DB_TYPE=postgres)

⁠MariaDB / MySQL (when DB_TYPE=mysql)

⁠SMTP / Email (optional)

⁠Demo Data

To start with sample data for testing:

docker exec budgetos node src/database/seed.js

This creates:

• Admin account: [email protected] / Admin123!
• Sample accounts, categories, and transactions

⁠Screenshots

Transactions	Reports

Forecast	Recurring

Bank Import	Categories

⁠Documentation

⁠Database Support

BudgetOS supports three database backends via Knex.js⁠:

⁠Volumes

⁠License

PolyForm Noncommercial 1.0.0⁠