ANDROID_DEPLOYMENT_GUIDE.md

HearthNet Android Deployment Guide

Quick Start: PWA (Progressive Web App) - RECOMMENDED ⭐

Status: ✅ Ready to use now - no APK build needed!

Install HearthNet on Android (ANY device, no installation required):

1. Start the HearthNet server on your computer:

   cd c:\Users\Chris4K\Projekte\HearthNet
   python app.py
   

2. Find your computer's IP address:

   ipconfig
   # Look for "IPv4 Address" under your network (e.g., 192.168.1.100)
   

3. On your Android device, open any browser (Chrome, Firefox, Edge, Samsung Internet):

   • Go to: http://YOUR_COMPUTER_IP:7860
   • Example: http://192.168.1.100:7860

4. Install as app (browser-specific):

   • Chrome/Edge: Menu → "Install app" or "Add to home screen"
   • Firefox: Menu → "Install"
   • Samsung Internet: Menu → "Add to home screen"

5. Done! 🎉 HearthNet is now on your home screen with:

   • Full offline support (Service Worker caching)
   • Native app appearance (standalone mode)
   • All features available

---

Alternative: Native APK Build (Advanced)

Why PWA is better:

• ✅ Works instantly - no build needed
• ✅ Updates automatically
• ✅ Works on Chrome, Firefox, Edge, Samsung Internet
• ✅ Smaller downloads (only web assets)
• ✅ No app store needed

APK Build Status:

• ⚠️ Requires complex local setup: Java 17 JDK, Gradle, Android SDK, cmdline-tools
• ⚠️ Build time: 5-15 minutes
• ⚠️ APK size: ~80-100 MB
• ✅ One-time setup, then works offline completely

If you want native APK anyway:

Option A: Android Studio GUI (Recommended)

1. Install Android Studio
2. File → Open → c:\Users\Chris4K\Projekte\HearthNet\build\android\HearthNetApp
3. Build → Build Bundle(s) / APK(s) → Build APK(s)
4. Find APK in: platforms/android/app/build/outputs/apk/debug/app-debug.apk
5. Install on device: adb install -r app-debug.apk

Option B: Docker (Container-based)

1. Install Docker Desktop
2. Run build container:

   cd c:\Users\Chris4K\Projekte\HearthNet\build\android
   docker build -f Dockerfile.build -t hearthnet-builder .
   docker run --rm -v $(pwd)\HearthNetApp:/project hearthnet-builder
   

Option C: Manual CLI Build

1. Install Java 17 JDK, Gradle, Android SDK cmdline-tools
2. Set ANDROID_HOME environment variable
3. Run: npx cordova build android --release
4. APK appears in: platforms/android/app/build/outputs/apk/

---

Testing Checklist

PWA Testing (5 minutes):

• Server running: python app.py
• Browser opens: http://YOUR_IP:7860
• Install option appears in menu
• App icon on home screen
• Offline mode works (disable WiFi, app still loads)
• Chat/Ask/Mesh features functional

APK Testing (if building):

• APK file generated (~80 MB)
• Device has USB Debugging enabled
• ADB recognizes device: adb devices
• Install: adb install -r app-debug.apk
• Tap launcher icon to open
• Enter server IP and connect
• Same features work as PWA

---

Features Available

Both PWA and APK include:

• ✅ Service Worker offline caching
• ✅ Local-first P2P mesh network
• ✅ Chat interface
• ✅ Ask (LLM) interface
• ✅ Mesh network topology view
• ✅ Landing page with server connection
• ✅ Persistent storage (localStorage)
• ✅ Background sync placeholder

---

Troubleshooting

"Cannot connect to server"

• Check computer is on same WiFi as Android device
• Verify server running: python app.py
• Try ping: ping 192.168.1.100 from Android (some WiFis block)
• Check firewall isn't blocking port 7860

PWA not installing

• Use Chrome/Edge/Firefox (Samsung Internet also works)
• Tap menu icon (⋮ or three dots)
• Look for "Install" or "Add to Home Screen"
• Not all browsers show this option

APK won't install

• Enable developer mode: Settings → About Phone → tap Build# 7 times
• Enable USB Debugging: Settings → Developer Options → USB Debugging
• Try: adb install -r app-debug.apk (includes -r flag to replace)

Build errors

• Run: npx cordova clean before rebuilding
• Remove: platforms/android folder and re-add platform
• Check Java: java -version returns 17+
• Check Android SDK: android list targets shows API 31+

---

Architecture

User Browser/App
     ↓
  PWA/APK
     ↓
 Cordova Wrapper (APK only)
     ↓
FastAPI Backend (http://localhost:7860)
     ↓
  HearthNet Mesh
     ↓
  P2P Network

---

Next Steps

1. Try PWA first (5 minutes):

   python app.py
   # Then open http://YOUR_IP:7860 on Android
   

2. If you need native APK:

   • Use Android Studio GUI (easiest)
   • Or follow Docker instructions
   • Or follow manual CLI instructions

3. Deploy to Play Store (future):

   • Sign APK with keystore
   • Create Google Play account
   • Upload and publish

---

Documentation Files

• PWA Implementation - Full web app details
• Cordova Build Guide - Detailed native build
• APK Setup - Project status
• Build Paths - Decision guide

---

Recommended: Start with PWA - it's production-ready now! 🚀