Skip to content

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:

DEVELOPMENT_TEAM = YOUR_TEAM_ID_HERE

Finding your Team ID:

  1. Go to https://developer.apple.com/account
  2. Click "Membership details"
  3. Copy the 10-character Team ID (e.g., HYA3HSRUJ8)

Verification:

flutter build macos --debug

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:

DEVELOPMENT_TEAM = YOUR_TEAM_ID_HERE

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.xcconfig with valid DEVELOPMENT_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:

flutter run -d chrome

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:

flutter run -d windows

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.

  • scope must include openid. 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. With unlisted_frontend_origin: deny-all it fails with a 400 instead. An unlisted plain http:// origin that isn't loopback (such as localhost or 127.0.0.1) fails with a 400 under either policy. This affects a web build hosted apart from the backend and flutter 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 as azp. The backend accepts only the accepted_azp_list values (default: that client_id); a deployment that sets the list must keep that client_id in 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

"Runner" has entitlements that require signing with a development certificate

Cause: Missing Local.xcconfig or DEVELOPMENT_TEAM not set.

Fix: Create Local.xcconfig with DEVELOPMENT_TEAM as shown above.

Keychain errors on macOS

OSStatus error -25293

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 ..
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