self/app

Self.xyz Mobile App

Quick Start

Run the interactive setup script to check and install all dependencies:

./scripts/setup-macos.sh

The script will prompt you to choose between:

1. Check only - Just show what's installed/missing
2. Interactive setup - Check and confirm before installing (recommended)
3. Auto-install - Install everything without prompts

You can also pass flags directly: --check-only or --yes

Requirements

macOS Setup

Core Dependencies

# Node.js 22+ (via nvm)
nvm install 22
nvm use 22

# Watchman
brew install watchman

# Ruby (via rbenv) - version specified in .ruby-version
brew install rbenv
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc
rbenv install   # Reads version from .ruby-version
rbenv rehash

# Ruby gems
gem install cocoapods bundler

# circom and snarkjs (for ZK circuits)
# Follow: https://docs.circom.io/ and https://github.com/iden3/snarkjs

Android Dependencies

# Java 17
brew install openjdk@17

Then install Android Studio and configure SDK/NDK (see Android Setup below).

iOS Dependencies

Install Xcode from the App Store (includes Command Line Tools).

Shell Configuration

Add the following to your ~/.zshrc (or ~/.bashrc):

# Java
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# Android
export ANDROID_HOME=~/Library/Android/sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools

Then reload your shell:

source ~/.zshrc

Installation

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

Install dependencies + build

yarn install-app

If you encounter any nokogiri build issues try running these commands first:

brew install libxml2 libxslt

bundle config build.nokogiri --use-system-libraries \
    --with-xml2-include=$(brew --prefix libxml2)/include/libxml2

bundle install

and rerun the command.

Android

Using Android Studio (Recommended)

1. Download and install Android Studio
2. Open Android Studio → Settings (or Preferences on macOS) → SDK Manager
3. Under SDK Platforms, install the platform with the highest API number
4. Under SDK Tools, check Show Package Details, expand NDK (Side by side), select version 27.0.12077973 and install
5. Enable USB debugging on your Android device (Settings → Developer options → USB debugging)

Using sdkmanager via CLI (Alternative)

If you prefer not to use Android Studio, you can install the SDK via command line:

1. Create a directory for the Android SDK (e.g., ~/android_sdk) and set ANDROID_HOME to point to it
2. Install sdkmanager according to the official instructions

# List available SDK platforms
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --list | grep platforms

# Install the latest platform (replace NN with 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.12077973"

# Install Platform Tools (for adb)
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install platform-tools

Set additional environment variables:

export ANDROID_NDK_VERSION=27.0.12077973
export ANDROID_NDK=$ANDROID_HOME/ndk/27.0.12077973

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.

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 in Xcode and add your provisioning profile in Targets > OpenPassport > Signing and Capabilities.

Then, install Ruby dependencies and CocoaPods:

cd ios
bundle install
bundle exec 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.

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

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.