Callbook docs
v1.0.0
Get help
● Start

Installation
server first, then the app.

Commands below were taken from app/README.md, server/README.md and server/package.json and match the project files.

npm cinpm run keygenflutter pub get

011. Install and run the server

Windows users

Flutter runs natively on Windows: use PowerShell for the flutter commands and Android builds (iOS builds need a Mac). For the server, either install Node.js 22.12+ for Windows and use PowerShell (replace cp .env.example .env with Copy-Item .env.example .env; there is no openssl by default, so use WSL or any random 64-character hex string), or run the commands in WSL 2 (Ubuntu) or Docker. npm run keygen is plain Node and works the same in PowerShell. macOS and Linux users can ignore this note.

  1. Check Node: node -v must print 22.12 or newer.
  2. Create the settings file:
    cd server
    cp .env.example .env
  3. Make a secret key and paste it after ADMIN_SECRET_KEY= in .env:
    openssl rand -hex 32
    Keep a copy somewhere safe. It encrypts the keys you save in the console.
  4. Install, build, start:
    npm ci
    npm run build
    npm start
    The server listens on port 8787. Test it: curl http://localhost:8787/healthz.
  5. Open the console at http://localhost:8787/admin and create the owner account (First sign-in).

Development shortcut: npm run dev builds and starts. Full check (type check, lint, tests, build): npm run check.

022. Create the signing key

The server co-signs receipt hashes with an Ed25519 key. Make one:

npm run keygen

It prints a private key (PEM text) and the public key. Paste the private key into the console under Signing and press Test. Keep a copy of the private key: it is shown only once. Until a key is saved, co-signing is off and receipts are sealed on the device only. Details: Signing.

033. Switch on the price providers

Binance public data is on by default and needs no key. For stocks and ETFs, paste your Twelve Data key under Price providers, press Test, then switch Twelve Data on. See Requirements.

044. Install and run the app

Windows users

Flutter runs natively on Windows: use PowerShell for the flutter commands and Android builds (iOS builds need a Mac). For the server, either install Node.js 22.12+ for Windows and use PowerShell (replace cp .env.example .env with Copy-Item .env.example .env; there is no openssl by default, so use WSL or any random 64-character hex string), or run the commands in WSL 2 (Ubuntu) or Docker. npm run keygen is plain Node and works the same in PowerShell. macOS and Linux users can ignore this note.

  1. Open a terminal in the app folder.
  2. Download packages:
    flutter pub get
  3. Run the tests (they need no device):
    flutter test
  4. Set your brand in lib/brand.dart (Rename and rebrand).
  5. Run on a device with your server: the address is the origin only, with no trailing path.
    flutter run --dart-define=API_BASE_URL=https://callbook.example.com
    Pick the connected phone or simulator when asked. Set the address for any real build: it is where prices come from. Without it the app uses built-in defaults and never contacts any server.
iOS first time

Run cd ios && pod install if Flutter asks for it, then open app/ios/Runner.xcworkspace in Xcode, select the Runner target, Signing & Capabilities, and choose your own team. The project ships with no team set.

Not run on a real device

The author ran the automated tests and built the app, but did not test it on a real phone. The share sheet, image sharing, the CSV share, store purchases and the first run against a live server are yours to test on your own devices before you publish.

05Do I need the server?

The app runs without it. Receipts are then sealed on the device only (the receipt says "Sealed on this device only") and no prices can be fetched, so calls on stocks, ETFs and crypto cannot be scored; only calls on custom assets can be settled, by hand. For the full experience (co-signing, price data, remote settings) run the server.