From d8b3a6956477352bb4038a22b6a5bf32735a6312 Mon Sep 17 00:00:00 2001
From: Davide Scaini <davide.scaini@alumni.cern>
Date: Sat, 25 Apr 2026 09:30:02 +0200
Subject: [PATCH] fix: allow HTTP to local instances in release build; fix
 activity 404 in dev
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Android release builds block cleartext HTTP by default (debug builds override
this via the debug manifest overlay). Add usesCleartextTraffic=true to app.json
so expo prebuild includes it in the generated manifest — required to reach local
Bincio instances over HTTP.

In bincio dev (Astro dev server), /activity/<id>/ routes 404 because
getStaticPaths() returns [] and there is no nginx try_files fallback. Add a Vite
middleware plugin to astro.config.mjs that rewrites /activity/<id>/ to /activity/
in dev, matching what nginx does in production.
---
 docs/mobile-app.md    | 65 +++++++++++++++++++++++++++++++++++--------
 mobile/app.json       |  1 +
 site/astro.config.mjs | 15 ++++++++++
 3 files changed, 70 insertions(+), 11 deletions(-)

diff --git a/docs/mobile-app.md b/docs/mobile-app.md
index cb7fe2c..e9b65f6 100644
--- a/docs/mobile-app.md
+++ b/docs/mobile-app.md
@@ -247,21 +247,64 @@ Everything else — the activity files, the extracted BAS JSON — stays on devi
 
 ---
 
+### Building a standalone APK
+
+A standalone APK is a **self-contained application binary** that runs without Expo Go and doesn't rely on development servers. Use this to distribute to friends, devices, or the Karoo 2.
+
+#### Option A: EAS cloud build (recommended, no local tools needed)
+
+```bash
+npm install -g eas-cli
+eas build -p android --profile preview   # produces a standalone APK
+```
+
+The APK is available for download from the EAS dashboard or via:
+```bash
+eas build -p android --profile preview --wait
+eas artifact download                     # follow the prompt
+```
+
+#### Option B: Local build with prebuild (requires Android Studio)
+
+```bash
+cd mobile
+npx expo prebuild --clean                 # generates Android native project
+cd android
+./gradlew assembleRelease                 # builds release APK
+```
+
+The APK is at `android/app/build/outputs/apk/release/app-release.apk`.
+
+**Note:** Release APKs must be signed. If signing fails, use `assembleDebug` instead to produce `app-debug.apk` (same as `npx expo run:android`).
+
+#### Troubleshooting
+
+If your friend's APK won't start:
+
+1. **Check device logs:**
+   ```bash
+   adb logcat | grep -i react  # requires Android SDK tools
+   ```
+
+2. **Ensure minimum Android version:** The app requires Android 5.0 (API 21) or higher.
+
+3. **Verify the APK is actually installed:**
+   ```bash
+   adb install /path/to/app.apk
+   ```
+
+---
+
 ### Distributing the app
 
 | Target | Method |
 |---|---|
-| Your own Android phone | `npx expo run:android` via USB, or EAS development build |
-| Karoo 2 | EAS production build → download APK → sideload via `adb install bincio.apk` or Karoo's app sideloader |
-| Other Android users | EAS build → share APK download link (no Play Store needed) |
-| Play Store | EAS production build → upload `.aab` to Play Console |
-| iOS users | EAS build → TestFlight (beta) or App Store |
-
-For Karoo sideloading:
-```bash
-eas build -p android --profile preview   # produces a standalone APK
-adb install /path/to/bincio.apk          # with Karoo connected via USB
-```
+| Your own Android phone | `npx expo run:android` via USB, or `eas build --local` |
+| Friends or testing | Standalone APK (release or debug, see above) — no Expo Go needed |
+| Karoo 2 | `eas build -p android --profile preview` → sideload via `adb install` |
+| Other Android users | Share the standalone APK download link |
+| Play Store | `eas build -p android --profile preview` → upload `.aab` to Play Console |
+| iOS users | `eas build -p ios --profile preview` → TestFlight (beta) or App Store |
 
 ---
 
diff --git a/mobile/app.json b/mobile/app.json
index 1c15c6a..e374ce0 100644
--- a/mobile/app.json
+++ b/mobile/app.json
@@ -10,6 +10,7 @@
     "platforms": ["ios", "android"],
     "android": {
       "package": "org.bincio.app",
+      "usesCleartextTraffic": true,
       "permissions": [
         "android.permission.READ_EXTERNAL_STORAGE",
         "android.permission.READ_MEDIA_VIDEO",
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 6bd511f..95e75cd 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -9,6 +9,20 @@ const env = loadEnv(process.env.NODE_ENV ?? 'development', process.cwd(), '');
 const apiPort = process.env.VITE_API_PORT || '4041';
 const serveTarget = env.PUBLIC_EDIT_URL || `http://localhost:${apiPort}`;
 
+// In production, nginx serves activity/index.html for all /activity/<id>/ URLs
+// via try_files. In dev (Astro dev server), no nginx — this plugin replicates it.
+const activityFallbackPlugin = {
+  name: 'activity-shell-fallback',
+  configureServer(server) {
+    server.middlewares.use((req, _res, next) => {
+      if (req.url && /^\/activity\/[^/]+\/?(\?|$)/.test(req.url)) {
+        req.url = '/activity/';
+      }
+      next();
+    });
+  },
+};
+
 export default defineConfig({
   integrations: [svelte(), tailwind()],
   devToolbar: { enabled: false },
@@ -16,6 +30,7 @@ export default defineConfig({
   // When hosting at a subdirectory (e.g. GitHub Pages project site), set:
   // base: "/repo-name",
   vite: {
+    plugins: [activityFallbackPlugin],
     optimizeDeps: {
       include: ['maplibre-gl'],
       esbuildOptions: { target: 'es2022' },