Deploy and Host Finance Tracker Lite with Railway

Finance Tracker Lite is the single-service edition of Finance Tracker: a private, multi-user household finance app that stores everything in an embedded SQLite database on a Railway volume — no database service to pay for. Accounts, balanced ledger transactions, budgets, recurring bills, and CSV import validation work exactly like the full edition.

About Hosting Finance Tracker Lite

Hosting deploys exactly one service: the Node application plus a persistent /data volume holding the SQLite file (WAL mode). Household members create accounts and record balanced postings; dashboards derive net worth, cash flow, and budget spending from posted ledger data. Signed sessions isolate households. Money is stored as integer minor units (EUR/USD cents, whole COP pesos). Because there is no database process, runtime cost stays at a single small service.

Choose Lite for the cheapest self-hosted household deployment. Choose the full Finance Tracker when you want managed PostgreSQL, managed backups, or expect many households per deployment.

Common Use Cases

Personal or shared household cash, card, loan, and savings tracking at minimum cost
Budget envelopes and monthly spending reviews
Upcoming recurring bills and income planning
Safe migration from spreadsheet or CSV transactions

Dependencies for Finance Tracker Lite Hosting

Node.js 24 application runtime (built-in node:sqlite, zero native dependencies)
Railway persistent volume mounted at /data for the database file

Deployment Dependencies

Implementation Details

Backups: use Railway volume snapshots plus the in-app JSON export. The SQLite file lives at /data/finance-tracker.db.

Why Deploy Finance Tracker Lite on Railway?

One service, one volume, one bill. Railway hosts the app with minimal configuration, private by default behind authentication, and you can scale vertically if your household grows.

Environment variables

None required — the card is zero-config. The following are set by the image; override only if you have a reason:

Name	Image default	Description
`DATABASE_PATH`	`/data/finance-tracker.db`	SQLite file path. Keep it inside the `/data` volume so data survives restarts and redeploys.
`PORT`	`3000`	HTTP listener; Railway injects it automatically.
`NODE_ENV`	`production`	Enables secure session cookies.
`SESSION_SECRET`	auto-generated at startup	Cookie-signing secret. If unset, sessions reset on each redeploy; set a stable random value (e.g. `openssl rand -hex 32`) for persistent logins.

Keep the service at 1 replica: the /data volume attaches to a single instance, and the app targets single-instance deployments.

Local setup

Copy .env.example to uncommitted .env.
Run npm ci, then npm run migrate (creates ./data/finance-tracker.db).
Run npm run dev; open the Vite local URL.

Deploy with Railway

Push this isolated repository to contourkde/finance-tracker-lite using /push-github.
Build and push the image: ./scripts/push-to-dockerhub.sh finance-tracker-lite --tag v0.2.0 (bump the tag in railway.json on every image change).
Verify with a real deploy: ./scripts/railway-e2e-deploy.sh finance-tracker-lite — attaches the /data volume and checks /healthz.
Publish via ./scripts/publish-template.sh finance-tracker-lite.