# 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://<desktop-LAN-IP>: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.