econumo/econumo: Econumo - A personal and family budgeting app with multi-currency support, shared accounts, and flexible budgets

A getting started guide to self-hosting Econumo — a personal finance & budgeting app

Econumo ships as a single, self-contained Go binary in a distroless Docker image. It serves both the API and the web app, runs database migrations automatically on boot, and works with SQLite (default) or PostgreSQL.

More screenshots — transactions, adding a transaction, sharing with family

Transactions	Adding a transaction
Manage money together	Works great on mobile

[!IMPORTANT]

The Docker image is now published to the GitHub Container Registry:

ghcr.io/econumo/econumo. The old Docker Hub image (econumo/econumo-ce)

belongs to v0.x and is no longer updated — update your docker-compose.yml

or pull references accordingly.

Quick start

You'll need Docker with Compose. The app itself is lightweight — it consumes up to 10 MB of RAM.

$ git clone --single-branch https://github.com/econumo/econumo
$ cd econumo
$ cp .env.example .env
$ docker compose pull && docker compose up -d

Then visit http://localhost:8181 and create the first user.

[!NOTE]

To build the image from source instead of pulling, run

docker compose up -d --build (the Dockerfile is in

deployment/docker/). Health is reported

at /health.

Configuration

Everything is configured through environment variables in .env — .env.example is the full, commented reference for every setting (database, mail, currencies, CORS, logging). The defaults work out of the box: SQLite storage and registration enabled; the only variables most setups ever touch are DATABASE_URL (to switch to PostgreSQL) and MAILER_DSN (to send password-recovery email).

CLI commands (create users, update currency rates, …) run through the binary inside the container, e.g.:

$ docker compose exec econumo /app/econumo user:create "Name" [email protected] password

Run without Docker (single binary)

Prefer not to use Docker? Every release also ships self-contained Linux binaries with the web UI embedded, runnable under systemd on a single host. See docs/run-without-docker.md for the full walkthrough.

Localization

All translations live in locales/ — one JSON catalogue per language, shared by the backend and the web app and managed right in the repository (no external translation platform). To contribute a language, copy locales/en.json, translate the values, and open a pull request — the test suite verifies key and placeholder parity between catalogues automatically.

Upgrading from v0.x (PHP)

v1.x is a full rewrite — the PHP backend became the Go binary and the Vue.js frontend became a React app. The result: memory consumption dropped from ~200 MB to ~10 MB, the app is much faster, and the new UI is a big step up. Your database is reused in place — accounts, passwords, and data keep working. See the migration guide for the step-by-step walkthrough (backup, new image, .env mapping, and the gotchas).

Next steps

Everything else — self-hosting (multi-currency, backups, CLI commands, debugging), the API, MCP, and the user guide — lives in the Econumo documentation.

Contact

• For release announcements, please check GitHub Releases or Econumo Website.
• For questions, issue reporting, or advice, please use GitHub Issues.

[!NOTE]

Econumo is funded by our GitHub Sponsors and Econumo (cloud) subscribers.

> If you know someone who might find Econumo useful, we'd appreciate if you'd let them know.