Textguard docs
v1.0.0
Get help
● Set up

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.

.envbrand.dartdart-define

01Server environment variables

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

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

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

ValueWhereMeaning
API_BASE_URL--dart-define=API_BASE_URL=https://... on flutter run / flutter buildYour server's origin. Empty means no server: built-in defaults.
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 free checks a day, the bundled 46-rule pack, 9 report offices and 6 lessons, "Suspicious" from 3 points, "Looks like a scam" from 6, the iOS filter moves a text to Junk from 5, the link expander off, history on, product ids empty.

04The server calls

CallWhen
GET /v1/configPublic, no login. Brand, paywall limits, features, scoring thresholds, the enabled rules, report contacts, lessons, announcement and update rule.
POST /v1/pingOnly if the user turned on "Anonymous usage count" in Settings (off by default).
POST /v1/expandOnly if you switch the link expander on in the console (off by default) and the user confirms a dialog. Otherwise 403 expander_off. See Privacy.
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 expander to 10. The full request and answer shapes and the rule engine specification are in contract/CONTRACT.md.