Sauci/docs/mobile-ota.md

Mobile over-the-air updates

Sauci ships JavaScript-only mobile changes over the air with expo-updates against a self-hosted XPREM update server (formerly expo-open-ota) at https://ota.apps.jbrunton.co.uk. XPREM speaks the official Expo Updates protocol, so the client is stock expo-updates; only the endpoint, the request headers, and the code-signing certificate are Sauci specific.

Store releases still follow Mobile release process. OTA never replaces a store build; it only refreshes the JavaScript bundle and assets of an already installed build.

Status

The client and checked-in native projects are wired with the real server values (app id 9a66f3c2-fda7-416f-87e2-6db833b32e9d and the Sauci code-signing certificate, SHA-256 fingerprint beginning DF:C9:17:A9). A new store build is required before updates can flow; see Server registration.

How it works

1. A build embeds a manifest URL, a release channel, an app id, and a public code-signing certificate.
2. On launch the app requests https://ota.apps.jbrunton.co.uk/manifest, sending expo-channel-name, expo-app-id, xprem-branch, and the standard expo-runtime-version and expo-platform headers.
3. XPREM resolves the channel to a branch, finds the newest update published for that branch and runtime version, and returns a signed manifest.
4. The client verifies the signature against the embedded certificate, downloads the bundle, and launches it on the next start.

Branches and channels

XPREM separates storage from delivery. A branch groups updates for a release line. A release channel is bound to a build at build time and points at a branch. Repointing a channel at a different branch promotes or reverts an update without a rebuild.

EAS build profile	RELEASE_CHANNEL	Publish branch
development	development	development
preview	staging	staging
production	production	production

Channels and their branch mappings are created in the XPREM dashboard under Channels. The client cannot create them.

Runtime version

apps/mobile/app.config.js sets an explicit runtime string:

runtimeVersion: '1.0.7'

The release version script updates this string with expo.version and the checked-in iOS and Android runtime values, so it remains the same value as the public app version. An update is only offered to builds whose runtime version matches exactly.

The practical rule: any change that touches native code, native dependencies, or the ios//android/ projects requires a new store build with a bumped expo.version. Bumping version starts a fresh runtime version on the server, so old builds stop receiving updates that assume the new native surface. JavaScript, asset, and configuration changes that do not alter the native binary can ship over the air against the current version.

An explicit runtime string is used because EOAS requires a concrete value for this checked-in bare workflow. The synchronized release script keeps it tied to the number visible in App Store Connect and Google Play without relying on Expo to resolve a policy during upload.

Client configuration

apps/mobile/app.config.js is a dynamic Expo config that spreads app.json and layers on the updates block. app.json remains the static source of truth for version, ios.buildNumber, and android.versionCode, which EAS rewrites during a release build.

Resolved configuration:

Key	Value
updates.url	https://ota.apps.jbrunton.co.uk/manifest
updates.enabled	true
updates.checkAutomatically	ON_LOAD
updates.fallbackToCacheTimeout	5000
updates.codeSigningCertificate	./certs/certificate.pem
updates.codeSigningMetadata	{ keyid: 'main', alg: 'rsa-v1_5-sha256' }
updates.requestHeaders['expo-channel-name']	process.env.RELEASE_CHANNEL, defaulting to development
updates.requestHeaders['expo-app-id']	process.env.XPREM_APP_ID
updates.requestHeaders['xprem-branch']	''
runtimeVersion	Explicit public version, currently 1.0.7

expo-updates only sends request headers that were declared at build time, so xprem-branch is declared even though it is empty. Removing it would not disable branch surfing, it would strip the header from every poll for the life of the install.

RELEASE_CHANNEL is set per profile in apps/mobile/eas.json. The config throws a descriptive error whenever RELEASE_CHANNEL is set but the committed certificate is missing or is the placeholder, so a misconfigured build fails at config resolution rather than shipping a client that can never validate a manifest.

Local development

The dev server serves bundles directly and no signed manifest exists, so disable code signing when running a dev client:

cd apps/mobile
DISABLE_CODE_SIGNING=1 npx expo start --dev-client

Code signing

XPREM signs every manifest with an RSA private key held by the server. The app embeds only the matching public certificate.

• apps/mobile/certs/certificate.pem is the public certificate. It is public key material and is committed.
• private-key.pem belongs to the update server only. apps/mobile/certs/.gitignore blocks it. It must never be committed or kept in a developer checkout.

The keypair is generated once, on the machine that configures the server:

npx eoas generate-certs

The certificate can also be downloaded from the XPREM dashboard App Info page for the Sauci app.

Native projects

apps/mobile/ios and apps/mobile/android are committed but generated by Expo CNG, and docs/releasing.md treats expo prebuild as a source change rather than a release step. The checked-in native projects embed the production updates configuration:

• ios/Sauci/Supporting/Expo.plist enables updates and contains the manifest URL, runtime version, request headers, code-signing metadata, and public certificate.
• android/app/src/main/AndroidManifest.xml enables updates and contains the same production configuration; android/app/src/main/res/values/strings.xml supplies its resolved runtime version.

The expo-updates config plugin wrote those values from the dynamic config as a reviewed source change. When future changes intentionally affect native config, regenerate and review the native diff separately:

cd apps/mobile
RELEASE_CHANNEL=production npx expo prebuild --clean
git diff   # retain only reviewed expo-updates native changes

--clean is required as of @bacons/apple-targets 5.x: running expo prebuild without it against an already-generated iOS project fails inside the widget target's Xcode project update step (withIosXcodeProjectBeta2BaseMod). A clean regeneration from the committed source avoids that failure. Run pod install in apps/mobile/ios afterwards to refresh Podfile.lock and the .xcworkspace before committing.

A build produced before this native source change will not check for updates.

Publishing an update

Publishing uses the XPREM CLI, eoas, pinned as a dev dependency of apps/mobile. Authentication is an app-scoped API token generated in the XPREM dashboard and supplied as EOO_TOKEN; it is a secret and must not be committed.

cd apps/mobile

# Verify the exact export environment without contacting the update server.
npm run ota:preflight:production

# Staging: consumed by builds made with the EAS `preview` profile.
EOO_TOKEN=<token> npm run ota:publish:staging

# Production.
EOO_TOKEN=<token> npm run ota:publish:production

The scripts resolve the matching EAS build profile into EOAS's export subprocess. EOAS sets EXPO_NO_DOTENV=1, so invoking eoas publish directly does not load profile values from eas.json. The wrapper injects the selected profile's public configuration, including the required API and hosted Auth values, sets the matching RELEASE_CHANNEL, and fixes the target branch. It does not print configuration values.

Production public API/Auth values come from the checked-in production profile. Staging uses the preview API value and requires the designated non-production Auth URL and anonymous key in the invoking environment; it rejects the production Auth origin. Run its safe export preflight with:

EXPO_PUBLIC_SUPABASE_URL=https://itbzhrvlgvdmzbnhzhyx.supabase.co \
EXPO_PUBLIC_SUPABASE_ANON_KEY=<non-production-anon-key> \
npm run ota:preflight:staging

npm run ota:doctor:production performs EOAS's read-only manifest probes using the production profile. It does not export or upload an update. Use the staging doctor command with the same non-production Auth environment as its preflight.

Useful flags to pass through to a publish command:

Flag	Purpose
--platform ios|android|all	Defaults to all.
-m "<text>"	Update description shown in the dashboard.
--rollout-percentage <1-99>	Progressive rollout to a fraction of devices.
--nonInteractive	Required in CI.

eoas publish refuses to run against a dirty git working tree. Commit first rather than reaching for --disableRepositoryCheck or EAS_NO_VCS=1; the published update records the commit it came from.

Publish only from a commit that has passed npm run verify:full. An OTA update reaches installed devices without store review, so it carries the same risk as a production deploy and none of the review latency.

Verifying a published update

curl -sD - "https://ota.apps.jbrunton.co.uk/manifest" \
  -H "expo-app-id: <xprem-app-id>" \
  -H "expo-channel-name: production" \
  -H "expo-runtime-version: 1.0.7" \
  -H "expo-platform: ios"

Rollback

Two mechanisms, in order of preference:

1. Repoint the channel. In the XPREM dashboard, map the affected channel to a branch holding the last known good update. This takes effect at each app's next update check and needs no rebuild and no republish.

2. Roll back from the CLI.

   cd apps/mobile
   EOO_TOKEN=<token> npm run ota:rollback
   

   eoas rollback publishes a rollback directive for a branch and runtime version, sending clients back to the bundle embedded in the store build. eoas republish can instead re-serve a specific earlier update.

A bad update that prevents the app from starting cannot be fixed over the air on devices that never complete a launch. Keep fallbackToCacheTimeout short and treat a startup-path change as store-release risk, not OTA risk.

Server registration

The Sauci app is registered on the XPREM server; the deployment itself is documented in the homelab repo (unraid/docs/xprem-ota.md).

Value	State
App id	9a66f3c2-fda7-416f-87e2-6db833b32e9d, hardcoded in apps/mobile/app.config.js (non-secret)
Code-signing certificate	Committed at apps/mobile/certs/certificate.pem (public half; CN=Sauci, valid to 2036, SHA-256 fingerprint DF:C9:17:A9:85:02:DD:EB:86:06:2B:64:8D:73:D2:8C:A2:AA:29:F0:AC:62:A8:76:62:A1:6B:A2:42:B0:3D:71)
Signing private key	Never leaves the server: keys mode database, sealed in the server's Postgres under its master key
Publish token	XPREM_SAUCI_API_KEY in the homelab repo .env; export as EOO_TOKEN when publishing
Channels	staging and production created server-side, mapped 1:1 to branches of the same names. development intentionally has no server channel — dev clients run with DISABLE_CODE_SIGNING=1 against the packager

Remaining before updates flow: cut a new store build from this checked-in native source. Only builds produced after that point can receive updates.