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 points to the third.
01Server environment variables
Copy server/.env.example to server/.env. Never publish this file.
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. macOS and Linux users can ignore this note.
| Name | Default | Purpose and where to get it |
|---|---|---|
ADMIN_SECRET_KEY | a generated file next to the database (data/admin-secret.key) | Encrypts the store keys saved in the console. 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/brierly.sqlite | The SQLite file. The console keeps its own file beside it. In Docker it is /app/data/brierly.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. |
The npm start script loads .env itself (node --env-file-if-exists=.env); there is nothing to install for that. When you run node dist/src/index.js yourself, set the variables in the environment.
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 App Store key and the Google Play service account). It is never sent anywhere. Think of it as the key to a small safe: the safe contents are useless without it.
- If you lose it: the saved store credentials cannot be read again. The console and the app keep working; only server-side purchase checking stops. Set a new
ADMIN_SECRET_KEY(openssl rand -hex 32), restart, and paste the store credentials into the Purchases page 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. - If you rotate it on purpose: there is no in-place re-encryption. Change the value, restart, and enter the store credentials again. Until you have, purchase checks cannot run; the app treats any answer other than an explicit "invalid" as "cannot check" and keeps the purchase result from the store on the device, so buyers are not locked out. The gap is that purchases made in that time are not recorded under Revenue.
- 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, https. Empty means no server: no questions arrive, local history and scores still work. |
| 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.
Built-in defaults: 5 sealed calls a week and 30 days of scored history without Pro, paywall on, product ids empty, leaderboard off, every other feature on.
04The server calls
| Call | When |
|---|---|
GET /v1/config | Public, no login. Brand, paywall limits, features, data attribution, announcement, update rule. |
GET /v1/questions, GET /v1/questions/:id | Open questions and one question. Never contain the crowd's odds. |
GET /v1/questions/:id/crowd | The crowd's odds, asked for only at the moment the user seals a call. |
POST /v1/resolutions | The app asks how the questions behind its open calls ended. All scores are computed on the phone. |
GET/POST /v1/leaderboard | Only if you switch the anonymous leaderboard on in the console and the user opts in. Off by default (otherwise 404 disabled). |
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 in the console. Otherwise the server answers 501 verification_off and the app trusts the purchase result from the store on the device. |
All /v1 routes are limited to 60 requests a minute per address (answer 429). The full request and answer shapes are in contract/CONTRACT.md.