money-balancer

Have you ever been on a group trip and lost track of who paid for what and who owes money to whom? If so, money balancer is the perfect tool for you! It helps you to keep track of who paid for what and calculates your balance with all of your friends. A demo is available here but it may be reset at any time.

Screenshots

Usage

Using docker-compose:

version: "3"
services:
  money-balancer:
    image: ghcr.io/dorianim/money-balancer
    restart: unless-stopped
    ports:
      - 8000:8000
    volumes:
      - ./data:/data
    environment:
      - MONEYBALANCER_JWT_SECRET=some_super_secret_secret

Using docker:

docker run -p8000:8000 -e MONEYBALANCER_JWT_SECRET=some_super_secret_secret -v $(pwd)/data:/data ghcr.io/dorianim/money-balancer

You can then access money-balancer on http://localhost:8000. The API documentation can be found at http://localhost:8000/api/v1.

Config options

General

• MONEYBALANCER_JWT_SECRET: a random value for the JWT signature

Authentication

Local

• MONEYBALANCER_AUTH_LOCAL_ENABLED: enable local username/password authentication

Proxy

Proxy authentication can be used with services like Authelia and Authentik

• MONEYBALANCER_AUTH_PROXY_ENABLED: enable proxy authentication
• MONEYBALANCER_AUTH_PROXY_HEADERS_USERNAME: header containing the username (e.g. X-authentik-username)
• MONEYBALANCER_AUTH_PROXY_HEADERS_NICKNAME: header containing the nickname (e.g. X-authentik-name)

If you want to use another sign on method, you may only protect the route /api/v1/auth/proxy.

For example in Authentik, you may use this as the unauthenticated paths:

^([^p]|p(p|r(p|o(p|xp)))*([^pr]|r([^op]|o([^px]|x[^py]))))*(p(p|r(p|o(p|xp)))*(r(o?|ox))?)?$

(excludes everything that contains proxy, generated with this tool)

How debts are split up:

• amount / debtors
• the potential rest is assigned to people who have to overpay
• who has to overpay is determined by how often they have overpaid in the past in this specific group

Development

You need Rust/Cargo and Node.js 22 with npm installed. Install client dependencies with cd client && npm ci. Build the release binary with the embedded client using

cargo build --release

This creates a static binary at target/release/money-balancer. Debug builds skip the client build and only compile the API.