Installation
app and server, step by step.
Commands below were taken from app/README.md and server/README.md and match the project files.
01Install and run the app
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.
- Open a terminal in the
appfolder. - Download packages:
flutter pub get - Run the tests (they need no device):
flutter test - Run on a device:
Pick the connected phone or simulator when asked.flutter run - With your server: add the address at build time. Origin only, no trailing path.
Without it the app uses its built-in defaults and never contacts any server.flutter run --dart-define=API_BASE_URL=https://textguard.example.com
Run cd ios && pod install if Flutter asks for it, then open app/ios/Runner.xcworkspace in Xcode and, for both the Runner and the TextguardFilter targets, open Signing & Capabilities and choose your own team and your own App Group (see Rename). The project ships with no team set (DEVELOPMENT_TEAM is empty), so Xcode asks for yours before the first device build.
The author built the app for Android and iOS, ran the automated tests and compiled the filter extension, but did not run the app on a real phone or emulator. In particular iOS has not yet called the filter extension: switch it on under Settings, Messages, Unknown & Spam and try it with a real text from an unknown number. The Android share-in and Check with Textguard are also untried on a phone. Test on your own devices before you publish.
02Install and run the server
- Check Node:
node -vmust print 22.12 or newer. - Create the settings file:
cd server cp .env.example .env - Make a secret key and paste it after
ADMIN_SECRET_KEY=in.env:
Keep a copy somewhere safe. It encrypts the store keys you save in the console.openssl rand -hex 32 - Install, build, start:
The server listens on port 8787. Test it:npm ci npm run build npm startcurl http://localhost:8787/healthzprints{"ok":true}. - Open the console at
http://localhost:8787/admin(next page: Console).
Development shortcut: npm run dev builds and starts. Full check (type check, lint, tests, build): npm run check.
03Do I need the server?
No. The app works fully offline with the rule pack bundled in app/assets/defaults/. The server is for operators who want to edit rule packs, report contacts and lessons without a new build, change the paywall limits, feature switches and scoring thresholds, show announcements, force an update, see opt-in install counts, confirm purchases with the stores and, if they accept the privacy cost, offer the link expander.