gemstone-nexus · Phase 6

Capacitor Android / iOS against live EC2

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
9DOC-CAPACITOR-LIVE-EC2Capacitor Android / iOS against live EC2referenceDevResources/docs/DOC-Capacitor-Live-EC2.mdAuth0 deferred (not required). Device UAT still open (`DOC-Device-UAT-Checklist.md`).12754381529d4f655ec67055f7af74cff171fc192026-07-22 18:33:18

Content

# Capacitor Android / iOS against live EC2

**Status 2026-07-21:** Engineering wiring COMPLETE for parallel-with-live-stack debug.
Auth0 deferred (not required). Device UAT still open (`DOC-Device-UAT-Checklist.md`).

**TLS (2026-07-21):** Live host serves a **Let's Encrypt** cert for
`gemstone.dataright.net` (HTTP-01 via `scripts/aws/provision-letsencrypt.sh`).
Prefer that hostname over the raw Elastic IP for Capacitor and browsers.

**Full workstation install playbook:** [`CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md`](CAPACITOR-ANDROID-INSTALLATION-PLAYBOOK.md).

## How Android runs against live EC2

Default debug path loads the **remote** SPA so asset `base` stays `/app/` for nginx web:

1. `frontend/capacitor.config.json` sets `server.url` → `https://gemstone.dataright.net/app`
   (override: `$env:CAPACITOR_SERVER_URL=...; npm run cap:sync` /
   `$env:CAPACITOR_USE_BUNDLED=1; npm run cap:sync` via `scripts/apply-capacitor-server.cjs`).
2. With the public LE cert, **debug `network_security_config` / `ec2_debug.crt` are
   obsolete for `gemstone.dataright.net`** (system CAs trust the chain). Those
   debug assets remain only as a fallback if you still hit the raw IP
   (`https://18.116.188.14`) with a self-signed leaf. Release builds never
   included the debug trust set.
3. API clients use `src/services/apiOrigin.js` — same-origin when on the live
   WebView; `VITE_API_BASE` or live default when bundled on `https://localhost`.

### Open in Android Studio

```powershell
cd frontend
npm install
npm run build
npx cap sync android
npm run cap:open:android
```

Then Run ▶ **app** (debug) on an emulator or USB device. First load hits the live
`/app/` SPA at `https://gemstone.dataright.net/app/`.

### assembleDebug without Studio

```powershell
cd frontend\android
.\gradlew.bat assembleDebug
# APK: app\build\outputs\apk\debug\app-debug.apk
```

### iOS (macOS)

```bash
cd frontend && npm run build && npx cap sync ios && npm run cap:open:ios
```

Public CA hostname needs no custom trust store. Raw-IP / self-signed remains an
ATS / trust-store problem (see `Info.plist` exception for the EIP only).

### Overrides

| Knob | Effect |
| --- | --- |
| `CAPACITOR_SERVER_URL` | Alternate live SPA URL (no trailing slash required) |
| `CAPACITOR_USE_BUNDLED=1` | Drop `server.url`; load `dist/` from the binary |
| `VITE_API_BASE` | Force REST/WS origin (no trailing slash), e.g. `https://gemstone.dataright.net` |
| Vite `base` | Keep `/app/` for web/nginx; bundled-native path later may use `./` |

### Web `/app/` unchanged

Vite `base: "/app/"` and `BrowserRouter basename="/app"` stay for EC2 nginx.
Capacitor does **not** rely on a second Vite base while `server.url` points at live.