From b4b1deafb8308f278d40f9ed00e0a5b6548ceff2 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Tue, 29 Sep 2026 18:12:57 -0400 Subject: [PATCH] =?UTF-8?q?docs(user):=20Android=20app=20guide=20=E2=80=94?= =?UTF-8?q?=20LAN=20setup=20and=20the=20Android=2016+=20local-network=20pe?= =?UTF-8?q?rmission?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Android 16+ gates per-app access to local networks behind a runtime permission; without it the app's LAN logins time out with zero packets leaving the phone (browser works — it is not per-app-gated). The new device guide covers the sideload install, first-run server URL, the permission prompt (and manual re-grant path), and a triage table for the login screen's error line. Per the user: overlay-VPN addresses are not a consideration and stay undocumented. --- docs/user/devices/android-app.md | 43 ++++++++++++++++++++++++++++++++ docs/user/user-guide.md | 6 +++++ 2 files changed, 49 insertions(+) create mode 100644 docs/user/devices/android-app.md diff --git a/docs/user/devices/android-app.md b/docs/user/devices/android-app.md new file mode 100644 index 0000000..108cd1c --- /dev/null +++ b/docs/user/devices/android-app.md @@ -0,0 +1,43 @@ +# Android App Setup Guide + +The Bookhoard Android app is the native mobile client: browse your libraries, read EPUBs, PDFs, comics and manga, and sync progress, highlights, bookmarks and notes with the server. + +## Prerequisites + +- ✅ A Bookhoard instance running and reachable from your phone's network +- ✅ The Bookhoard APK installed on your phone (Android 8.0+ / API 26+) +- ✅ Your phone connected to the same network as the server (for a self-hosted LAN setup) + +## Installing the app + +The app is distributed as a sideloaded APK: + +1. Copy the APK to your phone (USB, or any file-sync you trust) +2. Tap the APK to install — approve the "install unknown apps" prompt for the app you installed from (file manager, browser, etc.) +3. Upgrades install straight over the existing app and keep your data (login, downloads, reading state) + +## First run + +1. **Server URL** — enter your server's address. For a self-hosted LAN setup that is `http://:8765` (plain HTTP is expected here and fully supported; check the server machine's firewall allows port 8765 from your LAN) +2. **Log in** with your Bookhoard account +3. **Device registration** happens automatically — the app registers itself as a synced device so progress and annotations sync under your account + +## Android 16+: the local-network permission + +On Android 16 and newer, apps need explicit permission to talk to devices on your local network (and to non-HTTPS local addresses in general). **If the permission is missing, the app's logins to a LAN server time out with no visible cause** — the phone silently drops the traffic. + +- The app **asks for the permission by itself** during setup, as soon as you enter a local server address — grant it when prompted +- If it was denied (or you missed the prompt): **Settings → Apps → Bookhoard → Permissions → "Access local network devices" → Allow**, then try again +- Servers reached over the public internet (HTTPS) are not affected by this permission + +## Troubleshooting login failures + +The login screen prints the underlying error after "Could not reach server: …" — read it to narrow the cause: + +| Error | Meaning | What to check | +|---|---|---| +| `SocketTimeoutException` | The phone sent nothing that reached the server | On Android 16+ this is most often the **local-network permission** (above). Otherwise: wrong IP, phone on a different network/VLAN, or server down | +| `ConnectException` (connection refused/blocked) | The phone reached the machine but nothing answered | Server container down, or a firewall rejecting port 8765 | +| `UnknownHostException` | The hostname didn't resolve | Typo in the server URL, or a DNS/name issue (raw IPs avoid this) | + +To verify the server is reachable from the phone at all, open the same URL in the phone's browser — the browser is not subject to the per-app local-network permission, so if the browser works but the app times out on Android 16+, it is the permission. diff --git a/docs/user/user-guide.md b/docs/user/user-guide.md index c01cc2c..792a391 100644 --- a/docs/user/user-guide.md +++ b/docs/user/user-guide.md @@ -6,6 +6,12 @@ Welcome to the Bookhoard user documentation. This section contains guides for us Learn how to configure your e-reader devices to sync with Bookhoard: +- **[Android App Guide](devices/android-app.md)** - The native Android client + - Installing and upgrading the APK + - Connecting to a self-hosted server over LAN + - The Android 16+ local-network permission + - Troubleshooting login failures + - **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader - Installation on Kindle/Kobo/PocketBook - Plugin setup with server-side device approval