27 guides · synced daily from GitHub
OpenCount docs
Who paid, who owes, how to settle up. A self-hosted Tricount that installs on your phone like an app. One container, one SQLite file.
Introduction
Split expenses with friends, see who owes whom, settle up. A self-hosted, open-source alternative to Tricount that installs on your phone like an app.
Contributing
The long-form documentation lives in docs/ and is published at <https://orochibraru.com/opencount>. This file is the short version: what you need to get a change landed.
Getting started
Run OpenCount, create the admin account, and split a first bill.
Introduction
OpenCount is a self-hosted, open-source alternative to Tricount. People make a group for a trip, a flat or a dinner, log who paid for what, and see who owes whom and how to settle up. You run it on your own server, so the expenses of your friends and family stay there.
Showcase
A tour of OpenCount, one screen at a time. Desktop screens are shown in the dark theme at 1440 by 900, phone screens in the light theme at 390 by 844. Every name, group and amount is made up.
Install
OpenCount is distributed as a multi-arch Docker image (orochibraru/opencount) for linux/amd64 and linux/arm64. It needs one volume, mounted on /data, which holds the SQLite database: every account, group and expense. Lose it and you lose everything, so back it up (Backups and upgrades).
Configuration
There is no configuration file. The container reads a few environment variables at boot, and everything else (sign-ups, sign-in methods, email, receipt reading) is set by an admin in the app and stored in the database.
First run
From a fresh container to a first settled bill.
Using OpenCount
Groups, expenses, balances, and everything around them.
Groups and members
A group is one shared pot: a trip, a flat, a dinner, a club. Everything else (expenses, balances, categories, merchants, repeating expenses) belongs to one group, and only its members see it.
Expenses
An expense says who paid how much, when, for what, and who it was for. A group opens on its expenses, newest first, 50 at a time: Load more shows the next ones. The balances and totals at the top always count every expense, not just the ones loaded.
Balances and settling up
A member's balance is what they paid minus their share of everything. Positive, they are owed money; negative, they owe; zero, they are square. Every balance in a group adds up to zero, to the cent.
Repeating expenses
Rent, a subscription, the weekly groceries run: an expense that comes back on a schedule. Set it once and the server adds each copy on its date.
Categories and merchants
Every expense has a category, and can have a merchant. Both feed Insights, and both are filled in for you most of the time.
Scanning receipts
When an admin has turned receipt reading on, the expense sheet offers Scan a receipt while you add an expense. Pick a photo or a PDF and OpenCount fills in what it can read.
Insights
Each group's Insights page shows where its money went.
Personal expenses and bank sync
Personal is a private list of your own expenses. Nobody else sees it, not the other members of your groups and not the admin. It is in the bottom tab bar on a phone and the sidebar on a desktop.
Archiving
Done with a trip? Archive its group and it leaves your groups list.
Your account
Account holds five sections: profile, security, appearance, notifications and bank sync. Signing out is at the bottom of it.
Self-hosting
Running an instance for your friends, flat or family.
The admin area
Admin is where an instance is run from: who gets in, how they sign in, email, receipt reading and backups. It shows in the navigation for admins only; anyone else who opens its URL gets a 404, not a 403, so it doesn't announce itself.
Sign-in and single sign-on
Admin, Sign-in methods decides how people get in: email and password, passkeys, and any number of OpenID Connect providers. Password and passkey sign-in are on by default; there is no provider until you add one.
OpenCount sends these emails: invites, sign-up verification codes, password reset links, the code that confirms a new address and the notice to the old one, sign-in links and codes, and a test message. It sends them through an SMTP server you configure in Admin, Email; there is no built-in mail service and no third party.
Receipt reading
Receipt reading turns a photo or a PDF of a receipt into a prefilled expense: amount, date and merchant. It is off by default, optional, and entirely local. What members see is on Scanning receipts.
Backups and upgrades
What to back up. Taking a backup. Restoring. Upgrading. Downgrading. Why migrations are append-only.
Logs, traces and errors
OpenCount writes logs to the container's output, and can send traces to an OpenTelemetry collector and errors to a Sentry-compatible service. Traces and error reporting are off unless you configure them: with nothing set, no telemetry leaves the server.
Troubleshooting
The container exits at boot. Every form fails: "Cross-site POST form submissions are forbidden". I lost the setup code. The setup screen sends me to sign-in. Sign-ups won't turn on. Invites and codes never arrive. Passkeys aren't offered. Single sign-on fails after the provider. Everyone was signed out and email stopped working. Repeating expenses didn't appear. Scan a receipt is missing, or a PDF won't read. Reading the logs.
Contributing
Working on OpenCount itself.
Development
Without mise: bun install, copy .env.example to .env, and replace AUTH_SECRET with the output of openssl rand -base64 32.
Architecture
How OpenCount is put together, and why.
Testing
The suite runs on Bun's own test runner, with no Vitest and no Jest. It covers the domain logic (splits, balances, settle-up, recurrence, insights, receipt parsing, the category guess), the DTOs against a real SQLite database, the server modules (auth helpers, sign-up, setup, guards, origin check, secrets, mail, telemetry, migrations, the worker supervisor), the worker's job runner, the environment schemas, and components.