self/app/README.md

OpenPassport App

Requirements

Requirement	Version	Installation Guide
nodejs	> v18	Install nodejs
ruby	>= 3.1.0	Install ruby
circom	Latest	Install circom
snarkjs	Latest	Install snarkjs
watchman	Latest	Install watchman

Android

Requirement	Version	Installation Guide
Java	17	Install Java
Android Studio (Optional)*	Latest	Install Android Studio
Android SDK	Latest	See instructions for Android below
Android NDK	27.0.11718014	See instructions for Android below

* To facilitate the installation of the SDK and the NDK, and to pair with development devices with a conventient QR code, you can use Android Studio.

iOS

Requirement	Version	Installation Guide
Xcode	Latest	Install Xcode
cocoapods	Latest	Install cocoapods

Installation

All of the commands in this guide are run from the self/app directory

Install dependencies + build

yarn install-app

Android

Using Android Studio

In Android Studio, go to Tools > SDK Manager in the menu

Under SDK Platforms, install the platform with the highest API number

Under SDK Tools, check the Show Package Details checkbox, expand NDK (Side by side), select version 27.0.11718014 and install.

Using sdkmanager via CLI

Create a directory for the Android SDK. For example ~/android_sdk. Define the environment variable ANDROID_HOME to point that directory.

Install sdkmanager under ANDROID_HOME according to the instructions on https://developer.android.com/tools/sdkmanager

List available SDK platforms

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --list | grep platforms

In the list of platforms, find the latest version and install it. (Replace NN with the latest version number)

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install "platforms;android-NN"

Install the NDK

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install "ndk;27.0.11718014"

Define the environment variable ANDROID_NDK_VERSION to 27.0.11718014 and ANDROID_NDK to $ANDROID_HOME/ndk/27.0.11718014

Install Platform Tools, needed for the adb tool

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install platform-tools

Add $ANDROID_HOME/platform-tools to your $PATH variable

Run the app

Android

Pair and connect to the phone

Using Android Studio

In Android Studio, use Device Manager to pair with and connect to your phone.

Using adb

In your phone's developer settings, select Wireless debugging > Pair the device using a pairing code. Using the displayed information, run

adb pair PHONE_IP:PAIRING_PORT PAIRING_CODE

To connect to the device, find the IP number and port (different port than in the pairing step) directly under Wireless debugging, and run

adb connect PHONE_IP:DEVELOPMENT_PORT

Run the app

Create the file android/local.properties specifying the SDK directory, for example:

sdk.dir=/path/to/your/android/sdk

or create it with

echo sdk.dir=$ANDROID_HOME > android/local.properties

Launch the React Native server:

yarn start

Press a to open the app on Android.

To view the Android logs, use the Logcat feature in Android Studio, or use the adb logcat command-line tool.

EDIT: to test the app on android, see this issue temporarily

iOS

⚠️ To run the app on iOS, you will need a paying Apple Developer account. Free accounts can't run apps that use NFC reading.
Contact us if you need it to contribute.

Open the ios project on Xcode and add your provisioning profile in Targets > OpenPassport > Signing and Capabilities

Then, install pods:

cd ios
pod install

And run the app in Xcode.

Simulator Build

Note: iOS Simulator on Apple Silicon Macs requires Rosetta (x86_64) mode due to simulator architecture compatibility. If you're using a Silicon Mac (M1/M2/M3/M4), you may find that the Rosetta simulator build option is not available by default in Xcode.

To enable it, open Xcode and go to Product > Destination > Show All Run Destinations. This will unlock the ability to select the Rosetta build simulator, allowing you to run the app in the iOS Simulator.

Note: This is a simulator-specific issue - the app itself runs natively on ARM64 devices and builds without issues.

react-native-haptic-feedback v2.3.3

To create a successful build, "Target Membership" for the AudioToolbox.framework needs to be updated.

Pods Project > Frameworks > iOS > AudioToolbox.framework

Then click on the "+" button in the "Target Membership" box and add RNReactNativeHapticFeedback

more info

Modify the circuits

If you want to modify the circuits, you'll have to adapt a few things.

First, go to the circuit folder of the monorepo, modify the circuits and build them.

Then, upload the zipped zkeys and dat files at publicly available urls and replace the urls in app/src/utils/zkeyDownload.ts.

Adapt the input generation in common/src/utils/generateInputs.ts, and adapt and redeploy the contracts.

Android

Make sure that ANDROID_NDK_VERSION and ANDROID_NDK are defined as per the instructions above. Then build the android native module:

./scripts/build_android_module.sh

iOS

Find your development team id and run:

export DEVELOPMENT_TEAM="<your-development-team-id>"
./scripts/build_ios_module.sh

🚀 Deployment & Release

Quick Commands

# View current version info
node scripts/version.cjs status

# Create a new release (interactive)
yarn release              # Patch release (1.0.0 → 1.0.1)
yarn release:minor        # Minor release (1.0.0 → 1.1.0)
yarn release:major        # Major release (1.0.0 → 2.0.0)

# Deploy manually (with prompts)
yarn mobile-deploy        # Deploy both platforms
yarn mobile-deploy:ios    # Deploy iOS only
yarn mobile-deploy:android # Deploy Android only

# Version management
node scripts/version.cjs bump patch    # Bump version
node scripts/version.cjs bump-build ios # Increment iOS build
node scripts/version.cjs bump-build android # Increment Android build

Automated Deployments

Deployments happen automatically when you merge PRs:

1. Merge to dev → Deploys to internal testing
2. Merge to main → Deploys to production

To control versions with PR labels:

• version:major - Major version bump
• version:minor - Minor version bump
• version:patch - Patch version bump (default for main)
• no-deploy - Skip deployment

See CI/CD Documentation for details.

Manual Release Process

For hotfixes or manual releases:

# 1. Create a release (bumps version, creates tag, generates changelog)
yarn release:patch

# 2. Push to remote
git push && git push --tags

# 3. Deploy via GitHub Actions (happens automatically on merge to main)

The release script will:

• Check for uncommitted changes
• Bump the version in package.json
• Update iOS and Android native versions
• Generate a changelog
• Create a git tag
• Optionally push everything to remote

Version Management

Versions are tracked in multiple places:

1. package.json - Semantic version (e.g., "2.5.5")
2. version.json - Platform build numbers:

   {
     "ios": { "build": 148 },
     "android": { "build": 82 }
   }
   

3. Native files - Auto-synced during build:
   • iOS: Info.plist, project.pbxproj
   • Android: build.gradle

Local Testing

Android Release Build

# Build release APK
cd android && ./gradlew assembleRelease

# Or build AAB for Play Store
cd android && ./gradlew bundleRelease

# Test release build on device
yarn android --mode release

iOS Release Build

# Using Fastlane (recommended)
bundle exec fastlane ios build_local

# Or using Xcode
# 1. Open ios/OpenPassport.xcworkspace
# 2. Product → Archive
# 3. Follow the wizard

Troubleshooting Deployments

Version Already Exists

The build system auto-increments build numbers. If you get version conflicts:

# Check current versions
node scripts/version.cjs status

# Force bump build numbers
node scripts/version.cjs bump-build ios
node scripts/version.cjs bump-build android

Certificate Issues (iOS)

# Check certificate validity
bundle exec fastlane ios check_certs

# For local development, ensure you have:
# - Valid Apple Developer account
# - Certificates in Keychain
# - Correct provisioning profiles

Play Store Upload Issues

If automated upload fails, the AAB is saved locally:

• Location: android/app/build/outputs/bundle/release/app-release.aab
• Upload manually via Play Console

Build Optimization

The CI/CD pipeline uses extensive caching:

• iOS builds: ~15 minutes (with cache)
• Android builds: ~10 minutes (with cache)
• First build: ~25 minutes (no cache)

To speed up local builds:

# Clean only what's necessary
yarn clean:build  # Clean build artifacts only
yarn clean        # Full clean (use sparingly)

# Use Fastlane for consistent builds
bundle exec fastlane ios internal_test test_mode:true
bundle exec fastlane android internal_test test_mode:true

Maestro end-to-end tests

Install the Maestro CLI locally using curl or Homebrew:

curl -Ls https://get.maestro.mobile.dev | bash
# or
brew install maestro

Then build the app and run the flow:

yarn test:e2e:android  # Android
yarn test:e2e:ios      # iOS

The flow definition for Android is in tests/e2e/launch.android.flow.yaml and for iOS is in tests/e2e/launch.ios.flow.yaml.

FAQ

If you get something like this:

'std::__1::system_error: open: /openpassport/app: Operation not permitted'

You might want to try this:

watchman watch-del-all
watchman shutdown-server

Note on yarn reinstall

The yarn reinstall command deletes your yarn.lock and package-lock.json files and re-installs all dependencies from scratch. This means you may get newer versions of packages than before, even if your package.json specifies loose version ranges. This can sometimes introduce breaking changes or incompatibilities.

For example, as of this writing (July 29, 2024), a minor update to the Sentry Cocoa SDK (sentry-cocoa) breaks Xcode builds (see issue). If you run into unexpected build failures after a reinstall, check for updated dependencies and consider pinning versions or restoring your previous lockfile.

Tip: After running yarn reinstall, if you encounter new build issues, compare your new yarn.lock (or package-lock.json) with the previous version. Look for any package version changes, especially for critical dependencies. Sometimes, a seemingly minor update can introduce breaking changes. If you find a problematic update, you may need to revert to the previous lockfile or explicitly pin the affected package version in your package.json to restore a working build.