Installation

Installation #

Econumo is a single, self-contained Go binary. It serves both the API and the web app, runs database migrations by itself on every start, and stores data in SQLite by default (PostgreSQL is also supported). It is light: the server uses around 10 MB of RAM.

You can run it with Docker (recommended) or as a plain binary under systemd.

In this section #


Docker #

You need Docker with Compose.

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

Then open http://localhost:8181. The bundled docker-compose.yml runs the published image ghcr.io/econumo/econumo:latest, maps port 8181 on the host to port 80 in the container, and keeps the SQLite database in the db named volume (/app/var/db). The container reports its health to Docker through the built-in healthcheck command, which probes the /health endpoint.

All settings live in .env. The defaults work out of the box: SQLite storage and open registration. See Configuration for everything else.

Note The image is 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.

If you’d rather not clone the repository, a minimal docker-compose.yml is all you need next to your .env:

services:
  econumo:
    image: ghcr.io/econumo/econumo:latest
    env_file:
      - .env
    ports:
      - "8181:80"
    volumes:
      - db:/app/var/db
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/app/econumo", "healthcheck"]
      interval: 1m30s
      timeout: 10s
      retries: 12
      start_period: 30s

volumes:
  db:

with a .env holding at least:

DATABASE_URL=sqlite:///app/var/db/db.sqlite
PORT=80
ECONUMO_ALLOW_REGISTRATION=true

Without Docker (single binary) #

Every release also ships self-contained Linux binaries for linux/amd64 and linux/arm64, with the web app embedded. Download the binary for your architecture and verify it. On arm64 (e.g. a Raspberry Pi), use econumo-linux-arm64 here and below:

curl -LO https://github.com/econumo/econumo/releases/latest/download/econumo-linux-amd64
curl -LO https://github.com/econumo/econumo/releases/latest/download/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

Create a system user and the directories, install the binary, and write the environment file:

sudo useradd --system --home-dir /var/lib/econumo --shell /usr/sbin/nologin econumo
sudo mkdir -p /opt/econumo /var/lib/econumo /etc/econumo
sudo chown econumo:econumo /var/lib/econumo
sudo chmod 700 /var/lib/econumo
sudo install -m 0755 econumo-linux-amd64 /opt/econumo/econumo
sudo install -m 0600 /dev/null /etc/econumo/env
sudoedit /etc/econumo/env

A minimal /etc/econumo/env:

DATABASE_URL=sqlite:///var/lib/econumo/db.sqlite
PORT=8181

Save this unit as /etc/systemd/system/econumo.service:

[Unit]
Description=Econumo personal finance server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=econumo
Group=econumo
WorkingDirectory=/var/lib/econumo
EnvironmentFile=/etc/econumo/env
ExecStart=/opt/econumo/econumo serve
Restart=on-failure
RestartSec=5

# Hardening: the process only ever writes its database directory.
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/var/lib/econumo
UMask=0077

[Install]
WantedBy=multi-user.target

and start it:

sudo systemctl daemon-reload && sudo systemctl enable --now econumo

The binary also reads a .env file from its working directory if one exists, but variables already set in the environment always win.


Create the first user #

Open the app and sign up — registration is on by default. Once everyone in your household has an account, set ECONUMO_ALLOW_REGISTRATION=false and apply it with docker compose up -d.

You can also create users from the command line, with registration turned off:

docker compose exec econumo /app/econumo user:create "Name" user@example.com password

See CLI commands for this and the other management commands.


HTTPS and a reverse proxy #

Econumo speaks plain HTTP. To reach it from outside your network, put it behind a reverse proxy that terminates TLS (Caddy, nginx, Traefik, a Cloudflare Tunnel, …) and forwards requests to port 8181.

Then tell Econumo its public address:

ECONUMO_URL=https://money.example.com

ECONUMO_URL adds a link to every email, and it is required for single sign-on and for connecting AI apps such as Claude to the built-in MCP server by signing in. For MCP it must be an https origin with no path (plain http is accepted only for localhost).

Some features need the app to be opened over HTTPS (or on localhost): connecting a bank through SimpleFIN, for example, because the browser only encrypts the credentials on a secure page.

Behind a proxy, also see Reverse proxy and rate limits.


Upgrading #

Back up first (see Backups), then:

# Docker
docker compose pull && docker compose up -d

# Single binary: replace the file, then restart
sudo install -m 0755 econumo-linux-amd64 /opt/econumo/econumo
sudo systemctl restart econumo

Database migrations run automatically on start. /app/econumo version (or /opt/econumo/econumo version) prints the installed version, and the server checks once a day for a newer release and shows it in Settings (set ECONUMO_CHECK_UPDATES=false to turn that off). Release notes are on GitHub Releases and on econumo.com.

Upgrading from v0.x #

v1 is a full rewrite — the PHP backend became the Go binary and the Vue.js frontend became a React app — but it reuses your database in place: accounts, passwords and data keep working. The image name, the .env variables and the volumes changed, so follow the migration guide step by step.