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" [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.
To connect Claude or Codex to your instance over MCP with a browser sign-in,
see docs/mcp-setup.md.
Contact
[!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.
