Skip to content

Getting Started

Use this section when you are taking BillTracker from “empty server” to “ready to track bills.” The recommended install is Docker with one persistent /data mount for the SQLite database, backups, and app-owned runtime files.

Which path should I follow?

  •   New Docker install

    Create the data directory, write a Compose file, seed the first admin, start the container, and verify the app is reachable.

    Install with Docker

  •   First login

    Rotate the seeded password, create a regular bill-tracking user, confirm security settings, and decide what to enable first.

    First-run setup

  •   Existing install

    Back up /data, pull the next image, run migrations, verify the app, and know how to roll back if the upgrade does not look right.

    Upgrading

Fresh install checklist

  1. Pick the host path that will hold data, for example /portainer/hosting/bill-tracker/data.
  2. Create data/db and data/backups on that host.
  3. Generate a strong TOKEN_ENCRYPTION_KEY before production use.
  4. Set INIT_ADMIN_USER and INIT_ADMIN_PASS for the first start only.
  5. Start the container and open the app at the published port.
  6. Log in as the bootstrap admin.
  7. Create a normal user for bill tracking.
  8. Remove or rotate seed credentials after the first successful login.
  9. Put the app behind HTTPS before exposing it beyond a trusted LAN.
  10. Create a first backup before entering real financial data.

What should I know before installing?

Decision Recommended choice Why it matters
Runtime Docker Compose Keeps Node, the built frontend, migrations, and /data paths predictable.
Data path A host directory mounted to /data Replacing the container must not delete the SQLite database or backups.
Admin account Seed once with env vars The app needs an admin before it can be managed. Remove seed credentials after setup.
Daily use account Create a regular user Admins manage the server; normal users own bill-tracking data.
HTTPS Reverse proxy with trusted TLS Secure cookies, WebAuthn, and mobile browser behavior are all cleaner over HTTPS.
Encryption key TOKEN_ENCRYPTION_KEY outside the database Keeps encrypted SimpleFIN/OIDC/SMTP/TOTP secrets separate from a DB backup.

What does a healthy first install look like?

After setup:

  • docker ps shows the BillTracker container as running.
  • The web UI loads at your chosen URL.
  • The bootstrap admin can open the Admin area.
  • A regular user can log in and open Tracker, Bills, Calendar, and Settings.
  • /data/db/bills.db exists on the host.
  • /data/backups exists and is writable.
  • The Admin status page does not show migration or database errors.

How do I run it from source instead?

Source installs are useful for development. For production, prefer Docker.

npm install
npm run dev

For a production-style local build:

npm install
npm run build
npm start

The server listens on PORT, defaulting to 3000.

Next steps