Callbook docs
v1.0.0
Get help
● Set up

Configuration
every setting, where it lives.

Three places hold settings: build-time values in the app, the server's .env file, and the operator console. This page lists the first two and the API; the console sections are on the next page.

.envbrand.dartdart-define

01Server environment variables

Copy server/.env.example to server/.env. Never publish this file.

NameDefaultPurpose and where to get it
ADMIN_SECRET_KEYa generated file next to the databaseEncrypts the keys saved in the console (price-provider keys, signing key, store credentials). Make one with openssl rand -hex 32. Back it up: without it the saved keys cannot be read.
ADMIN_SETUP_TOKENa one-time code printed in the logThe code that creates the first console owner. Make one with openssl rand -hex 24 or leave empty. Remove it after the owner exists.
PORT8787HTTP port.
DATABASE_PATHdata/callbook.sqliteThe SQLite file. The console keeps its own file beside it. In Docker it is /app/data/callbook.sqlite.
TRUST_PROXY_HOPS0How many reverse proxies you control in front of the server. Use 1 behind Caddy or nginx. Wrong values make rate limits see the wrong address.
ADMIN_DEMO_PASSWORDunsetOnly for a public read-only demo console. Leave empty on a real install.

02If you lose or change ADMIN_SECRET_KEY

The key is the password the server uses to lock the secrets you paste into the console: the signing key, the price-provider keys and the store credentials. It is never sent anywhere.

  • If you lose it: the saved secrets cannot be read again. The app keeps working with the settings it already has, but co-signing and price fetching from keyed providers stop until you enter them again. Set a new ADMIN_SECRET_KEY, restart, and paste the signing key, provider keys and store credentials again. If you used the generated key file instead of the variable, copy that file along with the database when you move or restore the server.
  • Keep your signing key backup separately. If you replace the signing key, old co-signatures verify against the old public key only (Co-signing).
  • Never put the key in the app or in version control. It belongs in the server's environment only.

03App build-time values

ValueWhereMeaning
API_BASE_URL--dart-define=API_BASE_URL=https://... on flutter run / flutter buildYour server's origin. Empty means no server.
Brand, links, product idsapp/lib/brand.dartSee Rename.

With a server, the app loads GET /v1/config (cached 5 minutes, with an ETag). If the server is unreachable it uses the last copy it saved, then the built-in defaults. Server values override brand.dart values.

04The server calls

CallWhen
GET /v1/configPublic, no login. Brand, paywall limits, features, signing public key, claim-checking settings, markets on, announcement, update rule.
POST /v1/cosign, GET /v1/cosign/<hash>After a receipt is sealed, the app sends its 64-character hash and gets back a signed record. 501 cosign_off when no signing key is saved.
GET /v1/assetsThe assets the app offers (only those whose provider is switched on).
GET /v1/candles?asset=&from=&to=Closed UTC daily candles, at most 400 days. Today's candle is never returned.
POST /v1/pingOnly if the user turned on 'Share anonymous usage counts' in Settings (off by default).
POST /v1/purchases/verifyOnly if you switch verification on. Otherwise 501 verification_off and the app trusts the purchase outcome from the store on the device.

All /v1 routes are limited to 60 requests a minute per address (answer 429). Each price provider also has a per-minute limit toward the provider that you set in the console. The full shapes are in contract/CONTRACT.md.