Skip to content

First-Run Setup

First-run setup turns a freshly started container into a usable private bill tracker. The goal is simple: secure the bootstrap admin, create a real user, confirm the deployment settings, and make a first backup before entering important data.

What happens on first start?

BillTracker needs at least one admin account before the service can be managed. For Docker and other non-interactive starts, seed that admin with:

INIT_ADMIN_USER=admin
INIT_ADMIN_PASS=replace-with-a-long-password

Usernames must be at least 3 characters. Passwords must be at least 8 characters, but production passwords should be much longer.

When no users exist and the server is started from an interactive terminal, BillTracker can prompt for the first admin in the terminal. For containers, use the environment variables.

1. Sign in as the bootstrap admin

Open the app URL from your Docker install, for example:

http://your-server:3030

Sign in with the seeded admin username and password.

The bootstrap admin is for operating the server. It is not the normal account you should use to track bills.

2. Change the admin password

Before doing anything else:

  1. Open the admin/user area.
  2. Change the seeded admin password.
  3. Store the new password in your password manager.
  4. Remove or rotate INIT_ADMIN_USER and INIT_ADMIN_PASS in Compose.

This prevents a future container restart from reusing old seed credentials.

3. Create a regular user

Create a normal user account for bill tracking. That user owns personal financial records such as bills, payments, transactions, settings, and calendar feed tokens.

Use the admin account for:

  • User management
  • Auth configuration
  • Bank sync configuration
  • Backups and restores
  • Cleanup and notification settings
  • Status and migration checks

Use a regular user for:

  • Tracker planning
  • Bills and subscriptions
  • Payments
  • Calendar feed setup
  • Spending and bank transaction review
  • Personal settings

4. Confirm deployment settings

Before entering real financial data, review:

Area Where What to confirm
Data path Docker host /data/db/bills.db and /data/backups are on a persistent host mount.
HTTPS Reverse proxy Public access uses HTTPS and forwards X-Forwarded-Proto.
CSRF/cookies Environment/Admin docs CSRF_HTTP_ONLY=true, CSRF_SAME_SITE=strict, and secure cookies match your URL.
Secret encryption Admin → Bank Sync or docs TOKEN_ENCRYPTION_KEY is set if you want keys separate from the DB.
WebAuthn Admin/security RP ID and origin match the production domain before hardware-key 2FA.
Backups Admin → Backups The backup directory is writable and a manual backup succeeds.

5. Decide what to enable first

Start small:

  1. Add a few recurring bills manually.
  2. Record one payment so the Tracker flow is familiar.
  3. Enable the calendar feed if you want due dates in Apple/Google/Android calendar apps.
  4. Connect SimpleFIN only after basic bill tracking works.
  5. Configure service catalog/merchant matching once real transactions are syncing.

6. Create the first backup

After you create users and confirm the deployment:

  1. Open Admin → Backups.
  2. Run a manual backup.
  3. Confirm the backup appears in /data/backups.
  4. Keep a copy outside the app host if this is production.

What should I do after first-run setup?

  •   Add bills

    Create recurring bills, set due dates and cycles, add autopay details, and optionally mark debt fields.

    Add and manage bills

  •   Plan the month

    Use Tracker to see what is paid, due soon, late, projected, or overridden by bank-cleared payments.

    Plan a month in Tracker

  •   Connect bank sync

    Add SimpleFIN, sync transactions, review match suggestions, and tune service catalog matching.

    Connect your bank

Troubleshooting first login

Problem What to do
Seeded admin cannot log in Check the container logs for seed errors and confirm both INIT_ADMIN_USER and INIT_ADMIN_PASS were present on first start.
Password changed back after restart Remove or rotate seed env vars, then change the password again.
Regular user cannot access Admin Expected. Admin routes require an admin role.
Admin cannot see personal tracker data Expected. Use a regular user for bill-tracking data.
Browser login loops Check HTTPS/proxy cookie settings and the server time zone/time sync.

Next steps