FinanceTracking.app

Self-host FinanceTracking.app and set up the monthly workflow.

Choose a Docker path, verify the installation, and build your first budget in a safe order: accounts first, recurring structure second, then planning and real activity.

Covers Docker installation, safe upgrades, first-time setup, planning, everyday transactions, reports, and recovery.

Docs Getting Started

Self-host FinanceTracking.app with Docker

Why self-host FinanceTracking.app

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 to try the app privately on your computer. Developers can use the same checkout as a starting point.

$ 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, create an account, and confirm your budget is still available after restarting Docker.

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:v2.1.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

Production starts separate web and worker services from the same image. Confirm both are running before testing an account activity import or Backup v2 operation.

Published image providers

  • GitHub Container Registry: ghcr.io/taimoorq/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 app, confirm backups can be exported, and keep the database volume somewhere you intentionally manage.

The full GitHub README keeps the most detailed server 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 v2.1.0.
  4. Pull the new image and restart the production Compose stack.
  5. Confirm the production web and worker services are running. Then check Home, Plan, Activity, Accounts, Reports, and Backup before exporting a fresh backup.

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 Home, Plan, Activity, Accounts, Reports, and Backup.

Know when an update is available

The app notifies you when a new release is ready and shows what changed before you choose to install it.

What not to do

Do not run the sample-data command during a production update, and do not use latest when you want a predictable production rollout. Pin a version tag instead.

Version 2.1 needs the production worker. Confirmed account activity imports and Backup v2 exports and restores run in the background. Check both application services after updating, then confirm balances, totals, transactions, reports, and backups are still correct.

Finish the upgrade safely for each existing budget

The update keeps existing budgets available while you run checks. Back up first, run the commands below, and switch to the new calculations only after the results match.

Run the required upgrade checks

docker compose --env-file .env.production -f docker-compose.production.yml exec web bin/rails data_quality:legacy
docker compose --env-file .env.production -f docker-compose.production.yml exec web env APPLY=1 bin/rails target_backfill:all
docker compose --env-file .env.production -f docker-compose.production.yml exec web bin/rails target_shadow_reads:all
docker compose --env-file .env.production -f docker-compose.production.yml exec web bin/rails target_release:rehearse
docker compose --env-file .env.production -f docker-compose.production.yml exec web bin/rails target_release:status

What these checks confirm

  • Existing records pass the required safety checks.
  • The updated records contain no unresolved differences.
  • Old and new calculations agree without writing financial values to logs.
  • The upgrade and rollback steps complete successfully.
Do not finish the upgrade until every check passes. Take a PostgreSQL backup and application export first. Use the explicit enable and rollback commands in the GitHub README, and review any uncertain history in the app instead of guessing.

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 add the recurring transactions that belong in the month.
  5. Add one-off plan items, then record or import what actually happens in Activity.
  6. Match activity, check account balances, verify Reports, and close the month only when it is ready.

What makes the routine easier

  • Home explains the current financial position and keeps one clear next action prominent.
  • The attention list opens the plan items that are due, incomplete, or missing an actual amount.
  • Month pages keep planned income, planned spending, actual spending, and money left in view.
  • Import previews show which rows will import, which need correction, and how balances will change.
  • Filters only offer choices that apply to the current month.
  • Guided actions help you add paychecks, subscriptions, monthly bills, payment plans, and card payment estimates.
  • Recurring entries stay planned when they become due until you explicitly confirm payment.
  • Completed past months will not prompt you to add recurring items again.
  • Card payment estimates cover each minimum first, then direct extra available cash toward payoff.
  • Each signed-in user only sees their own months, imports, recurring transactions, and accounts.

Use Home to return to the next useful action

What Home is for

Home is the main landing page after sign-in. It shows setup progress, the current month, where your money stands, what needs attention next, recent months, yearly cash flow, and account summaries so you can quickly continue where you left off.

What needs attention

Open items that are still planned and due, missing key details, or marked paid without an actual amount. Each count opens the matching items for review.

Continue where you left off

Open the month that needs attention, then choose its Budget, Breakdown, Calendar, or Plan and Edit view.

See what moved

Review card purchases, card payments, money received, completed spending, and planned spending still left to pay. Open any non-zero total to see the transactions behind it.

One clear next action

Home prioritizes the most useful continuation based on the current month state while keeping Plan, Activity, Accounts, and Reports one navigation step away.

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 a balance snapshot whenever you want to give the app a fresh starting balance. Completed and planned transactions linked to that account build from it.

Current balance behavior

Current balance starts with the latest snapshot and adds completed transactions after that date. Projected balance also includes remaining planned transactions so you can see where the account may end the month.

Home and Reports tie-in

Home and Reports use linked account details to explain movement over time, including card additions, card payments, deposits, paid outflows, and remaining planned outflows.

Why add accounts early

Adding accounts early helps balances, payments, imports, backups, and payoff progress stay organized.

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 you add the recurring item to a month, its saved account is already selected.

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 keeps the card balance separate from the account making the payment, so payoff progress stays accurate.

Next, build and review a month

Move into the month

Once accounts and recurring transactions are ready, continue to Monthly Workflow for planning, Activity matching, reporting, close, and reopen.