Configuration
every setting, where it lives.
Two places hold settings: build-time values in the app, and the server's .env file. This page lists all of them.
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 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/dealproof.sqlite | The SQLite file. The console keeps its own file beside it. In Docker it is /app/data/dealproof.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 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, the verify route answers with an error (for example
503 not_configured) instead of a verdict. 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. Do the change in a quiet hour and expect it to take a few minutes. - 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: built-in defaults. |
| 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 free items, 10 free scans a month, a verdict needs 2 prices spread over 7 days inside a 30-day window, one return window (EU online purchase, 14 days), an empty Cycle Clock, currency rates off, product ids empty.
04The three server calls
| Call | When |
|---|---|
GET /v1/config | Public, no login. Brand, paywall limits, features, verdict thresholds, return windows, cycle clock, currency rates, announcement, update rule. |
POST /v1/ping | Only if the user turned on "Anonymous usage count" 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.