pediatric-ai-scribe-v3/docs/mobile-build.md

Mobile build & release

Capacitor 6 wrapper. Android only today; iOS project exists but requires macOS

• Xcode to produce an .ipa.

One-time setup

Keystore

keytool -genkeypair -v -keystore ~/pedscribe-release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 -alias pedscribe

Store the password in a password manager. Back up the .jks file off the machine. Losing it = can't sign updates; Play Store requires signature continuity (unless you're on Play App Signing).

Android Studio (optional, IDE workflow only)

export CAPACITOR_ANDROID_STUDIO_PATH="/snap/android-studio/current/bin/studio.sh"
npx cap open android

CI build (preferred)

Tag-triggered. Push any vX.Y.Z tag → .github/workflows/android-release.yml builds a signed APK on a GitHub runner and attaches it to the matching release.

Required repo secrets (set once, via Settings → Secrets and variables → Actions or gh secret set):

• ANDROID_KEYSTORE_BASE64 — base64 -w0 ~/pedscribe-release.jks
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEY_ALIAS — pedscribe
• ANDROID_KEY_PASSWORD

Tag a release:

# conventional-commits prefix auto-tags (see CONTRIBUTING.md)
git commit -m "feat: ..."  && git push      # auto-version workflow bumps minor
git commit -m "fix: ..."   && git push      # auto-version workflow bumps patch

# or force an exact version
scripts/release.sh 6.2.0 --push

APK lands at the GitHub release; /releases/latest link in the login page resolves to it automatically. Obtanium subscribers (github.com/<owner>/<repo>) pick up the update on next poll.

Local build (fallback / debugging)

cd mobile
npm install
npx cap sync android
cd android
./gradlew assembleRelease \
  -Pandroid.injected.signing.store.file=$HOME/pedscribe-release.jks \
  -Pandroid.injected.signing.store.password='<pass>' \
  -Pandroid.injected.signing.key.alias=pedscribe \
  -Pandroid.injected.signing.key.password='<pass>'

Output: android/app/build/outputs/apk/release/app-release.apk For Play Store, swap assembleRelease → bundleRelease; output: .aab under bundle/release/.

Single-quote the password

Keystore passwords with shell metacharacters (), $, !, space, etc.) must be single-quoted. Backslash line continuations get eaten by some terminal paste handlers — prefer one-line commands.

Reinstall on device

adb install -r android/app/build/outputs/apk/release/app-release.apk

-r keeps app data (saved server URL, auth token in Keystore, IndexedDB).

Gotchas

• JDK 17 only. Newer JDK (21/25) breaks Android Gradle Plugin. Set org.gradle.java.home=/usr/lib/jvm/java-17-openjdk-amd64 in ~/.gradle/gradle.properties if the system default is different.
• QEMU multi-arch Docker builds fail with SIGILL on native modules (argon2). Docker Hub workflow is x86-only. Use a native ARM runner if you need ARM64.
• npx cap must run inside mobile/, not repo root.
• Foreground recording on Android 14+ requires foregroundServiceType="microphone" in AndroidManifest.xml plus the 3-arg startForeground(id, notif, TYPE_MICROPHONE). Already applied.
• Mic "denied" after permission grant — WebView intercepts the prompt. Fix: long-press app icon → App info → Permissions → Microphone → Allow.

Files

Path	Purpose
mobile/capacitor.config.json	app ID, name, WebView config, plugin opts
mobile/src/	launcher HTML (server URL entry)
mobile/android/app/src/main/java/com/pedshub/scribe/MainActivity.java	JS bridge + WebView mic permission
mobile/android/app/src/main/java/com/pedshub/scribe/AudioRecordingService.java	foreground service for background recording
mobile/android/app/src/main/AndroidManifest.xml	permissions, intents, backup rules
.github/workflows/android-release.yml	CI build