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.
01Server environment variables
Copy server/.env.example to server/.env. Never publish this file.
| Name | Default | Purpose and where to get it |
|---|---|---|
ADMIN_SECRET_KEY | a generated file next to the database | Encrypts 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_TOKEN | a one-time code printed in the log | The code that creates the first console owner. Make one with openssl rand -hex 24 or leave empty. Remove it after the owner exists. |
PORT | 8787 | HTTP port. |
DATABASE_PATH | data/callbook.sqlite | The SQLite file. The console keeps its own file beside it. In Docker it is /app/data/callbook.sqlite. |
TRUST_PROXY_HOPS | 0 | How 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_PASSWORD | unset | Only 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
| Value | Where | Meaning |
|---|---|---|
API_BASE_URL | --dart-define=API_BASE_URL=https://... on flutter run / flutter build | Your server's origin. Empty means no server. |
| Brand, links, product ids | app/lib/brand.dart | See 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
| Call | When |
|---|---|
GET /v1/config | Public, 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/assets | The 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/ping | Only if the user turned on 'Share anonymous usage counts' in Settings (off by default). |
POST /v1/purchases/verify | Only 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.