Getting started¶
On a server¶
curl -fsSL https://raw.githubusercontent.com/Emadhabibnia1385/KasbBook/main/scripts/install.sh | sudo bash
You need Debian or Ubuntu, Python 3.11 or newer, and Docker if you want the installer to provide PostgreSQL and Redis for you.
It asks for three things: a bot token from @BotFather, the bot's username, and — optionally — the public https URL this API will be served at. That last one is what makes the bot's API screen link to your own documentation, and it is required if you ever switch to webhooks. Leave it blank and nothing links anywhere, which is better than linking somewhere dead.
Everything else it generates — the database password, the signing key, the webhook path secret — because a secret a person chooses is a secret a person can guess.
Prompts are read from your terminal, not from standard input, because standard
input under curl ... | bash is the script itself. To install with no terminal
at all, answer from the environment instead:
curl -fsSL https://raw.githubusercontent.com/Emadhabibnia1385/KasbBook/main/scripts/install.sh \
| sudo TELEGRAM_BOT_TOKEN=... TELEGRAM_BOT_USERNAME=YourBot \
KASBBOOK_API_URL=https://your.host bash
Running it again is safe. It repairs a half-finished install, leaves an
existing .env alone, and adds anything missing from it.
When it finishes:
If it does not say that, it prints the last fifteen log lines and exits non-zero rather than claiming success. See troubleshooting.md.
On a laptop¶
No Docker, no PostgreSQL, no token needed for the tests.
git clone https://github.com/Emadhabibnia1385/KasbBook.git
cd KasbBook
python3 -m venv venv
./venv/bin/pip install -r requirements-dev.txt
./venv/bin/python -m pytest tests -q
To actually run the bot, you need a token and a database. SQLite is the default, so this is enough:
export TELEGRAM_BOT_TOKEN=...
export TELEGRAM_BOT_USERNAME=YourBot
export KASBBOOK_DATABASE_URL="sqlite+aiosqlite:///kasbbook.db"
./venv/bin/alembic upgrade head
./venv/bin/python apps/bot/runner.py
And the API:
export KASBBOOK_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')
PYTHONPATH=src ./venv/bin/uvicorn --factory kasbbook.api.app:create_app --reload
Then open http://127.0.0.1:8000/docs.
First run, as a user¶
1. Say /start. The bot has never seen this messenger account, so it hands
you a one-time code and asks you to claim it. That code is how a Telegram
account becomes attached to a KasbBook account rather than being one — see
data-model.md for why that distinction matters.
2. Make a book. Personal, business, team or organization. The type is not cosmetic: a team book gets payroll and member shares, a personal one does not, and the default scope for a transaction follows from it.
3. Record something. Either press through the buttons, or just type:
Income, category "فروش", 250,000. Behind it, a balanced journal entry was
written; trial_balance() on that book now returns two equal numbers.
4. Ask for a report. Reports run on the Jalali calendar. 1403-05 is
Mordad of 1403 — converted to a Gregorian range before the query, so the
database never sees a Jalali value and you never see a Gregorian one.
The daily list¶
📅 Daily list, on the home screen, opens today across every book you are on — a team, your shop, your household — in one list. It is the first generation's daily screen, brought back:
- a summary per book, split the way a shopkeeper reads a day: business income and expense, personal spending, installments, and what the day left over;
- new at the top, already set to that day;
- previous and next day, or type any date in either calendar;
- a filter per book when you are on more than one.
Books are never added together. A team's revenue is not its members' savings, and two books in two currencies do not sum to anything.
📌 Record a transaction is the other way in, and it starts the entry rather than opening a menu: tap the kind, name the category, type the amount — which saves it. Today is assumed and the heading says which day it assumed, so the date is one tap to change and still editable on the saved card.
What to set up next¶
| Reminders | A daily digest at an hour you choose, in your timezone. On by default at 21:00 — a bookkeeping tool that never speaks first is one people forget to open. |
| Budgets | A ceiling per category. The bot warns as you approach it, not after. |
| Recurring rules | Rent, salary, subscriptions. Defined once, booked when due, and it catches up if the bot was down. |
| A second messenger | Link Bale or Rubika to the same account from the identities screen. Same books, different app. |