Penge.

A calmer plan for every paycheck.

Version 1.0 · Released 28 October 2026 · MIT

Know what your income needs to cover — and what you have left.

Quick start · Features · Self-hosting guide · Testing and limitations

_{Demo account and invented amounts. Every new installation starts with its own empty database.}

Your paycheck, with a plan

Penge helps you give each paycheck a purpose: bills, subscriptions, loan payments, savings and everyday spending. Set up the recurring items once, then follow up on what you have paid.

You enter the figures yourself. There is no bank connection and no need to record every individual transaction.

What you can do

💸 Plan each paycheck Budget from one payday to the next. Carry money forward only when you choose to.	✅ Keep track of payments Mark individual payments as paid. Pay ahead and choose which paycheck funds them.
🔁 Manage recurring costs Bills, subscriptions and minimum loan payments, with dated changes when amounts go up or down.	🌱 Make room for savings Savings accounts, recurring transfers, balance adjustments and purchase plans.
🔒 Keep budgets separate Invite-only accounts, private financial APIs and administrator tools for invitations and access.	✉️ Stay in touch Branded invitations and password recovery, plus Markdown newsletters with preview and unsubscribe.

Also included: light and dark themes, a mobile layout, Home Screen installation, JSON export/import and CSV mapping.

Current scope: Norwegian Bokmål interface and NOK. Balances are user-maintained estimates. Penge does not provide bank synchronization, automatic transaction imports, interest/amortization calculations, multi-currency accounting or full offline editing.

One step at a time

New accounts begin with a focused walkthrough: set your income, add your commitments, then review your budget before saving.

Quick start

You need Docker Engine + Docker Compose v2, Git and a Linux server with roughly 2 GB free memory and enough persistent disk. The app runs Node 24 inside Docker; you do not need to replace your host's Node installation.

1. Get the source

git clone https://github.com/08Robfin/penge.git
cd penge

2. Create your private configuration

python3 scripts/create-env.py

This creates a mode-600 .env with a unique instance name and fresh, independent database and authentication secrets. It refuses to overwrite an existing configuration.

For an HTTPS installation, choose its exact origin on the first run and use this generator command:

python3 scripts/create-env.py --url https://budget.example.org

Alternatively, copy .env.example and choose a unique COMPOSE_PROJECT_NAME and replace the secret placeholders yourself. Never reuse another installation's secrets or commit your real .env.

3. Start Penge

docker compose up -d --build
docker compose ps

Open http://localhost:3000 on the server. The default listener is loopback only. The stack initializes its own PostgreSQL volume and applies migrations before starting the app and mail worker.

4. Create your first account

docker compose run --rm tools run admin -- invite you@example.org

Open the printed invitation link privately and register with a unique password. Then grant your account administrator access:

docker compose run --rm tools run admin -- grant-admin you@example.org

Refresh Penge. Administrasjon now lets you invite people and manage access.

The source contains no existing users or budgets, and a fresh installation never connects to the developer's running instance.

Email that belongs to your instance

Set RESEND_API_KEY or SMTP_URL, plus a verified MAIL_FROM, in your private configuration. Keep the mail worker running.

• Invitations explain Penge and include a personal registration link.
• Forgot password sends a short-lived, single-use link for an existing account. It never creates a new account.
• Newsletters share the same design, support Markdown and include privacy, operator credit and unsubscribe links.

Without a delivery provider, invitations can be copied manually. Password recovery, verified email changes and newsletter sending require email configuration.

Email setup and delivery details →

Your data and your server

Penge stores financial data in your own PostgreSQL database. Public APIs scope financial records to the signed-in account. Passwords use Argon2id, and queued emails are encrypted.

Infrastructure administrators still have technical access to the database. Penge is a hobby project, not a bank or professional financial service. It has had limited internal and automated testing, not a professional security audit or independent penetration test. There is no guarantee that it is secure, correct or suitable for your data; use it at your own risk. See testing and limitations.

Before inviting real users, configure HTTPS, a suitable privacy notice and encrypted backups with an off-server recovery copy. Newsletter membership currently defaults on; review the consent requirements for your use case.

Version 1.0

This repository is the released 1.0 source snapshot. The author's running server may change independently. Day-to-day server changes are not automatically synchronized here, and no further releases or maintenance are promised. A future version, such as 1.1, will be published only if the owner chooses to do so.

GitHub does not deploy to the server and holds no production credentials. Scheduled dependency-update pull requests are disabled. Anyone may use or modify this version under MIT.

For a deliberate future upgrade, see the upgrade and rollback guide. Never run docker compose down -v on an installation whose data you want to keep.

Find your way

Guide	What it covers
Self-hosting	HTTPS, networks, persistence and first-time setup
Configuration	Every environment variable and operator branding
Email	Resend/SMTP, templates, delivery and unsubscribe
Backups and recovery	Encrypted archives and isolated restore verification
Upgrades	Controlled releases and rollback
Development and tests	Node 24, isolated fixtures, Git checks and CI
Testing and limitations	What was checked and what is not guaranteed
Contributing	Focused changes and review expectations

Troubleshooting

• Startup fails: check that secrets are independent and the application origin is exact. Never paste .env into an issue.
• 403 after changing domains: update BETTER_AUTH_URL to the browser's origin, then recreate app/worker containers.
• Mail stays pending: check the worker and private provider/sender configuration.
• Data seems missing: confirm COMPOSE_PROJECT_NAME and the intended existing volume before changing anything.
• Old Home Screen icon: refresh the site or reinstall the shortcut.

Built with

Next.js · React · TypeScript · Better Auth · Argon2id · PostgreSQL · Zod · Docker Compose

Automated checks cover tests, types, builds, dependencies, secret patterns, source and container images. These are limited checks, not security certification. Screenshots use synthetic data.

License

MIT — use, self-host, modify and share Penge, including commercially. Preserve the copyright and license notice. The Robfin.no service credit remains in the app; MIT does not require a visible UI credit. Third-party dependencies retain their own licenses.