# OpenPassport App

## Requirements

| Requirement | Version  | Installation Guide                                                       |
| ----------- | -------- | ------------------------------------------------------------------------ |
| nodejs      | > v18    | [Install nodejs](https://nodejs.org/)                                    |
| ruby        | >= 3.1.0 | [Install ruby](https://www.ruby-lang.org/en/documentation/installation/) |
| circom      | Latest   | [Install circom](https://docs.circom.io/)                                |
| snarkjs     | Latest   | [Install snarkjs](https://github.com/iden3/snarkjs)                      |
| watchman    | Latest   | [Install watchman](https://facebook.github.io/watchman/)                 |

### Android

| Requirement                 | Version       | Installation Guide                                                                    |
| --------------------------- | ------------- | ------------------------------------------------------------------------------------- |
| Java                        | 17            | [Install Java](https://www.oracle.com/java/technologies/javase-jdk17-downloads.html)  |
| Android Studio (Optional)*  | Latest        | [Install Android Studio](https://developer.android.com/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](https://developer.apple.com/xcode/) |
| cocoapods   | Latest  | [Install cocoapods](https://cocoapods.org/)         |

## Installation

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

Install dependencies + build

```bash
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
```bash
$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)
```bash
$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --install "platforms;android-NN"
```

Install the NDK
```bash
$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
```bash
$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
```bash
echo sdk.dir=$ANDROID_HOME > android/local.properties
```


Launch the React Native server:

```bash
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](https://github.com/zk-passport/openpassport/issues/191) temporarily

### iOS

> :warning: To run the app on iOS, you will need a paying Apple Developer account. Free accounts can't run apps that use NFC reading.<br/>
> 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](https://github.com/mkuczera/react-native-haptic-feedback/issues/142)

## 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](https://chat.openai.com/share/9d52c37f-d9da-4a62-acb9-9e4ee8179f95) and run:

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

## 🚀 Deployment & Release

### Quick Commands

```bash
# 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](./docs/MOBILE_DEPLOYMENT.md) for details.

### Manual Release Process

For hotfixes or manual releases:

```bash
# 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:
   ```json
   {
     "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

```bash
# 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

```bash
# 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:
```bash
# 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)
```bash
# 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:
```bash
# 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:

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

Then build the app and run the flow:

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

The flow definition for Android is in [`tests/e2e/launch.android.flow.yaml`](tests/e2e/launch.android.flow.yaml) and for iOS is in [`tests/e2e/launch.ios.flow.yaml`](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](https://stackoverflow.com/questions/49443341/watchman-crawl-failed-retrying-once-with-node-crawler):

```
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](https://github.com/getsentry/sentry-cocoa/issues/5648)). 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.