econumo

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.

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" user@example.com 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.

To connect Claude or Codex to your instance over MCP with a browser sign-in, see docs/mcp-setup.md.

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.