Developer Setup Guide
Platform-specific setup instructions for building and running Soliplex.
Prerequisites
- Flutter SDK, stable channel — exact version in
.fvmrc(see below) - Xcode (for iOS/macOS)
- CocoaPods (
gem install cocoapods) - Android Studio (for Android)
Flutter SDK version
.fvmrc at the repository root names the exact SDK CI builds and tests with,
and is the only place that version is written. Match it locally:
fvm use # with fvm: reads .fvmrc; run commands as `fvm flutter ...`
flutter --version # without fvm: install that version, check what your shell resolves
fvm is convenient, not required. .fvmrc is plain JSON, read with jq rather
than by invoking fvm, so any tool or a human can read it too.
fvm use pins the project but does not change what bare flutter resolves
to — run fvm global as well, since the pre-commit hooks call flutter
directly. Homebrew cannot pin a version: brew install flutter tracks the
latest release.
The environment: floor in pubspec.yaml (flutter: ">=3.47.0") is a
different number: the oldest SDK this library promises consumers. It may lag
.fvmrc, and moves only when a dependency forces it.
Using VS Code, and the analyzer disagrees with the pin? See Troubleshooting.
Quick Start
# Install dependencies
flutter pub get
# Run the app
flutter run -d macos # or: -d ios, -d chrome, -d android
Platform Setup
The supported targets are iOS, Android and the web. The macOS, Linux and Windows runners are for running the app locally while developing: no CI job builds them and nobody tests them before a release, so a dependency change can break one without anyone noticing.
macOS
Code Signing (Required for Keychain)
macOS apps require code signing to access Keychain for secure token storage. Each developer must configure their own Apple Developer Team ID:
# 1. Copy the template
cp macos/Runner/Configs/Local.xcconfig.template macos/Runner/Configs/Local.xcconfig
# 2. Edit Local.xcconfig and uncomment/set your Team ID
Your Local.xcconfig should contain:
Finding your Team ID:
- Go to https://developer.apple.com/account
- Click "Membership details"
- Copy the 10-character Team ID (e.g.,
HYA3HSRUJ8)
Verification:
If configured correctly, Keychain operations succeed and auth tokens persist across app restarts.
Without code signing: The app runs but Keychain fails silently. Auth works per-session but tokens don't persist, requiring re-login on each launch.
iOS
Code Signing (Required for Physical Devices)
iOS uses the same xcconfig pattern as macOS:
# 1. Copy the template
cp ios/Runner/Configs/Local.xcconfig.template ios/Runner/Configs/Local.xcconfig
# 2. Edit Local.xcconfig and uncomment/set your Team ID
Your Local.xcconfig should contain:
Privacy Descriptions (Info.plist)
The file_picker dependency links against Photos.framework, so iOS requires
NSPhotoLibraryUsageDescription in ios/Runner/Info.plist. This is already
configured — if you add new plugins that access protected resources (camera,
microphone, location, etc.), add the corresponding NS*UsageDescription keys.
Simulator vs Device
- Simulator: No signing required for debug builds
- Physical device: Requires
Local.xcconfigwith validDEVELOPMENT_TEAM
Building for TestFlight/App Store
Build releases with the version in .fvmrc — a stable-channel release.
Beta/dev-channel binaries can fail App Store validation.
# Confirm the SDK you build with is the one in .fvmrc
fvm flutter --version # or: flutter --version, without fvm
# Build release IPA
flutter build ipa --release
# Upload using Transporter app
open -a Transporter build/ios/ipa/soliplex_frontend.ipa
Android
No special signing setup required for debug builds.
Release Signing
Release builds (flutter build apk --release, flutter build appbundle,
flutter run --release) sign with the app's release keystore and fail without
it. The keystore and its passwords are not in the repo; get them from whoever
cuts releases, keep the keystore outside the repo, and create
android/key.properties (gitignored):
storePassword=<store password>
keyPassword=<key password>
keyAlias=soliplex
storeFile=/absolute/path/to/soliplex-release.jks
Without it, a release build stops at packaging with
SigningConfig "release" is missing required property "storeFile".
Every release must be signed with the same keystore: Android refuses to install an APK over one signed by a different key.
Web
No special setup required:
Linux
# Install GTK dependencies (Ubuntu/Debian)
sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev
# The video player plays through libmpv, which it loads at run time
sudo apt-get install libmpv2
flutter run -d linux
Windows
Requires Visual Studio with "Desktop development with C++" workload:
The video player plays through libmpv, which better_player_windows does not
ship. Download the 64-bit mpv-2.dll from
mpv-player-windows
and copy it beside the built app, build\windows\x64\runner\Debug\ (again
after flutter clean).
On either platform, without libmpv every video waits 30 seconds, then offers to open in the browser.
Backend sign-in settings
These live in the backend's OIDC config (oidc/config.yaml in the installation,
or each path in its oidc_paths) or, where noted, in the identity provider's
client settings. They're not in this repo, but the app depends on them. In
oidc/config.yaml, scope and accepted_azp_list are set per auth system,
under auth_systems; allowed_frontend_origins and
unlisted_frontend_origin may also be set once at the top of the file, for
every auth system in it.
scopemust includeopenid. Without it the identity provider issues no ID token: sign-out can't name the session to end, and the account name and identity fall back to the access token.- Web sign-in from an origin other than the backend's own asks the user to
confirm on a backend page, unless the origin is listed in
allowed_frontend_origins. Withunlisted_frontend_origin: deny-allit fails with a 400 instead. An unlisted plainhttp://origin that isn't loopback (such aslocalhostor127.0.0.1) fails with a 400 under either policy. This affects a web build hosted apart from the backend andflutter run -d chrome, whose port makes it a different origin: ask the backend's operator to list the origin, or confirm the page each time. Cancelling on that page leaves you on the backend's page, which never sends you back; return to the app yourself. - Native apps sign in with the backend's own
client_id(from/api/login), so their tokens carry it asazp. The backend accepts only theaccepted_azp_listvalues (default: thatclient_id); a deployment that sets the list must keep thatclient_idin it, or native sign-in succeeds at the identity provider and then every request is refused. - In the identity provider's client settings, the web app's origin must be
allowed for cross-origin requests (Keycloak: the client's Web Origins,
with the app's origin, or
+when the app is served from the backend's origin). On web, token refresh is a browser request straight to the provider's token endpoint. Without that setting, every refresh fails as a network error, the session is never renewed, and it ends only when the backend refuses a request with an expired token.
Troubleshooting
Analyzer errors that don't match the code
Cause: The Dart extension analyses and debugs with whatever SDK is on
PATH unless told otherwise, so it can disagree with the version in .fvmrc.
The errors it reports never name a version, so the mismatch does not announce
itself.
Fix: Point the extension at the pin. fvm use does it for you, writing a
version-specific dart.flutterSdkPath into .vscode/settings.json and
rewriting it on every switch — which is what keeps it correct. Leave that file
alone; .vscode/* is gitignored, so the churn never reaches a commit.
"updateVscodeSettings": false stops fvm writing the file at all, leaving you
to point at the version-agnostic .fvm/flutter_sdk by hand. Don't — the
flag lives only in the tracked .fvmrc, so it leaves yours permanently dirty
in git status and one git add from landing on everyone.
No dart.flutterSdkPath is committed: every path fvm can offer lives under
.fvm/, which a developer without fvm does not have, so a committed setting
would point at nothing on their machine.
Entitlements require signing
Cause: Missing Local.xcconfig or DEVELOPMENT_TEAM not set.
Fix: Create Local.xcconfig with DEVELOPMENT_TEAM as shown above.
Keychain errors on macOS
Cause: Missing or invalid code signing configuration.
Fix: Follow the macOS code signing setup above.
Pod install fails
# Clean and reinstall
cd ios && pod deintegrate && pod install && cd ..
cd macos && pod deintegrate && pod install && cd ..
Related Files
| File | Purpose |
|---|---|
macos/Runner/Configs/Local.xcconfig.template |
Template for macOS signing |
macos/Runner/Configs/Local.xcconfig |
Your macOS signing config (gitignored) |
ios/Runner/Configs/Local.xcconfig.template |
Template for iOS signing |
ios/Runner/Configs/Local.xcconfig |
Your iOS signing config (gitignored) |
ios/Runner/Info.plist |
iOS privacy descriptions and app config |
android/key.properties |
Your Android release signing config (gitignored) |
.gitignore |
Excludes **/Local.xcconfig |
.fvmrc |
The Flutter SDK version CI builds with |