Brierly 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 points to the third.

.envbrand.dartdart-define

01Server environment variables

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

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. macOS and Linux users can ignore this note.

NameDefaultPurpose and where to get it
ADMIN_SECRET_KEYa 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_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/brierly.sqliteThe SQLite file. The console keeps its own file beside it. In Docker it is /app/data/brierly.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.

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

ValueWhereMeaning
API_BASE_URL--dart-define=API_BASE_URL=https://... on flutter run / flutter buildYour server's origin, https. Empty means no server: no questions arrive, local history and scores still work.
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.

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

CallWhen
GET /v1/configPublic, no login. Brand, paywall limits, features, data attribution, announcement, update rule.
GET /v1/questions, GET /v1/questions/:idOpen questions and one question. Never contain the crowd's odds.
GET /v1/questions/:id/crowdThe crowd's odds, asked for only at the moment the user seals a call.
POST /v1/resolutionsThe app asks how the questions behind its open calls ended. All scores are computed on the phone.
GET/POST /v1/leaderboardOnly if you switch the anonymous leaderboard on in the console and the user opts in. Off by default (otherwise 404 disabled).
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 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.