Expense Tracker

Self-host Expense Tracker and set up the monthly workflow.

This page explains why the app is self-hosted, how to install or update it, and the easiest setup order: accounts first, recurring transactions second, then the month workflow.

Updated for v0.9.0 on July 16, 2026. Covers self-hosting, Docker setup, first success, updates, Overview, trusted account balances, and connecting recurring transactions to accounts.

Docs Getting Started

Self-host Expense Tracker with Docker

Why self-host Expense Tracker

Budgeting data is personal: account names, balances, imported files, notes, recurring bills, and backup files can reveal a lot about how a household works. Self-hosting lets you decide where that data lives, who can sign in, how backups are stored, and when updates are applied.

What you are responsible for

The public website does not host user budgets. If you run the app, you operate the server, database, credentials, access controls, backups, HTTPS, and update timing for that installation.

Quick local start

Use this path when you want the fastest local trial or you plan to develop from a checkout.

$ git clone https://github.com/taimoorq/expense_tracker.git
$ cd expense_tracker
$ cp .env.example .env
$ docker compose up --build

Open the app at http://localhost:4287. The local Compose stack builds the app image from your checkout and starts PostgreSQL for you.

Production from published images

Use a version tag when you want a repeatable self-hosted install without rebuilding the app image on the server.

EXPENSE_TRACKER_IMAGE=ghcr.io/taimoorq/expense_tracker:v0.9.0
docker compose --env-file .env.production -f docker-compose.production.yml pull web
docker compose --env-file .env.production -f docker-compose.production.yml up -d --no-build

You can also use the Docker Hub mirror by setting EXPENSE_TRACKER_IMAGE=docker.io/<dockerhub-username>/expense-tracker:v0.9.0. Replace <dockerhub-username> with the Docker Hub namespace used for the project.

Published image providers

  • GitHub Container Registry: ghcr.io/taimoorq/expense_tracker
  • Docker Hub: docker.io/<dockerhub-username>/expense-tracker

Release tags

  • vX.Y.Z and X.Y.Z point to a specific app release.
  • latest tracks the newest release image.
  • sha-<commit> points to the exact workflow commit.
Production checklist before you expose the app. Set real secrets, decide who can sign in, put HTTPS in front of the Rails app, confirm backups can be exported, and keep the database volume somewhere you intentionally manage.

The full GitHub README keeps the most detailed operator instructions, including production HTTPS, update flow, and environment variables. Start there for server installs: Published Docker Images.

Keep a self-hosted install updated

Published image update path

  1. Read the latest release notes in the app or on GitHub.
  2. Review the repository .env.example for new settings you may want to copy into your own environment file.
  3. Update EXPENSE_TRACKER_IMAGE to the release tag you want, such as v0.9.0.
  4. Pull the new image and restart the production Compose stack.
  5. Confirm the app loads, then export a fresh backup after the upgrade settles.

Source checkout update path

  1. Export a backup before changing the running app.
  2. Pull the latest repository changes from git.
  3. Review environment changes and local release notes.
  4. Run the normal setup or restart flow so database changes are applied.
  5. Sign in and check the current month, recurring setup, accounts, and backup page.

How the app helps

The app checks GitHub Releases, shows update prompts when a newer version is available, and keeps in-app release notes so operators can see what changed before pulling a new image or source checkout.

What not to do

Do not load demo data as part of a normal production update, and do not use latest when you want a predictable production rollout. Pin a version tag instead.

Verify the update before calling it done. Open the current month, check Recurring Transactions, open Accounts & Net Worth, visit Backup & Restore, and export a fresh backup after the new version is running normally.

Set up accounts and recurring items first

Recommended first steps

  1. Add your main checking, savings, card, and debt accounts, and optionally record balance snapshots.
  2. Save recurring transactions for the incoming and outgoing items you expect.
  3. Create a new month or clone the most recent one.
  4. Open Plan and Edit to add those recurring transactions to the month.
  5. Add one-off entries manually as the month unfolds.
  6. Mark items paid, update actuals, and review the month in Budget, Breakdown, and Plan and Edit, using Grouped, Full List, or Calendar inside Budget.

Helpful app behaviors

  • The Overview page explains the current financial position and keeps one clear next action prominent.
  • The attention queue opens exact Month Review modes for due items, missing details, missing actual amounts, and auto-completed entries.
  • The compact month summary rail keeps planned income, planned outflow, actual outflow, and leftover context visible inside the month workspace.
  • Institution-activity import previews show source coverage and balance effects before an account import is applied.
  • Reason-based filters only show values that actually exist in the current month.
  • Plan and Edit includes guided actions for paychecks, subscriptions, monthly bills, payment plans, and card payment estimates.
  • Some entries created from recurring transactions can automatically mark themselves paid when due.
  • Recurring generation actions hide in older months that already look complete.
  • Estimated card payments add minimums for active cards first, then use leftover cash to increase those payments when the month has room.
  • Each signed-in user only sees their own months, imports, recurring transactions, and accounts.

Use Overview to return to the next useful action

What the Overview page is for

The Overview page is the main landing page after sign-in. It highlights the current month, the current financial position, one clear next action, an exact attention queue, recent month context, year cash flow, and account summaries so you can restart from evidence instead of deciding where to click next.

Exact attention queue

Open items that are still planned and due, missing key details, paid without an actual amount, or auto-completed and waiting for confirmation. Each count opens the matching Month Review result.

Current month access

Use the continue card, recent month links, or month jump control when you want to reopen the month most likely to need attention, then jump straight into Budget, Plan and Edit, or Calendar.

Account movement

Use the account movement panels to review credit card additions, card payments, bank money in, paid outflows, and planned outflows still left to pay. Non-zero totals include review links so you can open the entries behind the number.

One clear next action

Overview prioritizes the most useful continuation based on the current month state while keeping month navigation and account context available nearby.

Connect the budget to accounts and net worth

What belongs here

Use Accounts & Net Worth for manual checking, savings, brokerage, retirement, cash, asset, and liability balances. You can record point-in-time snapshots, review current and projected balances, and keep account context visible without relying on bank syncing.

Snapshot workflow

Add balance snapshots whenever you want a fresh reconciliation point for an account. The app uses that snapshot as the base for later paid and planned linked activity.

Current balance behavior

Current balance is based on the latest snapshot plus paid linked entry activity after that snapshot date. Projected balance adds remaining planned activity so you can see what the account should look like if the month finishes as planned.

Overview tie-in

The Overview uses linked account details to show account movement over time, including credit card additions, card payments, bank deposits, paid outflows, and remaining planned outflows.

Why add accounts early

Linked accounts make month views, recurring setup, account filters, backup restores, movement details, payoff progress, and account totals more accurate.

Connect recurring transactions to the accounts they affect

How to think about it

  • Add recurring transactions for the repeating monthly activity you expect, such as paychecks, bills, subscriptions, payment plans, and card payments.
  • Link each recurring item to the account it affects so month views are easier to scan and account tracking stays useful.
  • If you prefer, you can still type an account label manually, but choosing a saved account usually gives the cleanest long-term workflow.
  • When months, imports, or restores reuse those items later, the app carries that account context forward where it can.

Credit card payments

  • Link the card payment recurring item to the card account that is being paid down.
  • Also link the checking, cash, or other funding account that will make the payment.
  • This lets the app treat the card itself separately from the account that actually sends the money, and gives card account pages the data they need for payoff progress.

Next, build and review a month

Move into the month

Once accounts and recurring transactions are ready, the next page to read is Monthly Workflow. That page covers month creation, Plan and Edit, imports, recurring actions, and review.