Configuration
every setting, where it lives.
Three places hold settings: the server's .env file, build-time values in the app, and the operator console. This page lists the first two.
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 (the WebSocket relay uses the same port). |
DATABASE_PATH | data/hometether.sqlite | The SQLite file. The console keeps its own file beside it. In Docker it is /app/data/hometether.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 and sign-in limits see the wrong address. See Relay. |
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 locks the secrets you paste into the console (the App Store key and the Google Play service account). It is never sent anywhere.
- 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 key, restart, and enter the store credentials again. If you used the generated key file instead of the variable, copy that file with the database when you move or restore the server.
- 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 and flutter build | Your server's origin (https, no trailing path). Empty means no server: the parent's own remote and the guided fixes work, remote help is off. |
| 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). Values you set in the console override the matching values in brand.dart. Missing keys fall back to built-in defaults. The relay is on the same address at wss://your-server/v1/relay, unless you set a different public relay address in the console.
04Server calls the app makes
| Call | When |
|---|---|
GET /v1/config | Public, no login. Brand, paywall, features, relay limits, supported TV text, guided fixes, announcement, update rule. |
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 the server answers 501 verification_off. |
POST /v1/pairing, POST /v1/pairing/claim, GET|DELETE /v1/pairing/helpers..., DELETE /v1/pairing/self | Pairing a helper with a parent, listing and removing helpers. |
GET /v1/relay (WebSocket) | The relay. |
All /v1 HTTP routes are limited to 60 requests a minute per address (answer 429). Request and answer shapes are in contract/CONTRACT.md.