Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs(koreader): rewrite setup guide for plugin + server-side approval flow

Browse Source 
Replace the outdated Calibre-wireless/Basic-Auth instructions with the
actual current flow: install the bookhoard.koplugin plugin, enter the
server URL in the plugin menu, then approve the pending registration
from Settings → Devices. Registration tokens are delivered to the
plugin automatically after approval (5-minute expiry), so no
credentials are ever typed on the device.

Also document bidirectional sync of position, bookmarks, highlights
(colors mapped between web and KOReader palettes), and notes, plus
format-aware SHA-256 book matching, OPDS delivery, and trimmed
troubleshooting sections covering the new registration flow.
This commit is contained in:
john-okeefe
2026-08-20 14:14:39 -04:00
parent 995ccb50bb
commit 54d0550dec
1 changed files with 70 additions and 406 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/devices/koreader-setup.md
+69 -405
View File
@@ -9,18 +9,19 @@ KOReader is an open-source e-reader application that supports a wide range of e-
- Kindle devices (Paperwhite, Oasis, Voyage, etc.) - Kindle devices (Paperwhite, Oasis, Voyage, etc.)
- Kobo devices (Clara, Aura, Nia, etc.) - Kobo devices (Clara, Aura, Nia, etc.)
- PocketBook devices - PocketBook devices
- Android tablets and phones
It also runs on Android tablets and phones, although Bookhoard's dedicated mobile apps (coming later) will be the better option there.
## Prerequisites ## Prerequisites
Before you begin, make sure you have: Before you begin, make sure you have:
- ✅ A Bookhoard instance running and accessible on your network - ✅ A Bookhoard instance running and accessible on your network
- ✅ Your Bookhoard credentials (username and password) - ✅ A web browser logged in to your Bookhoard account (for device approval)
- ✅ A KOReader-compatible e-reader device - ✅ A KOReader-compatible e-reader device
- ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance - ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance
## Installation ## Installing KOReader
### Kindle Devices ### Kindle Devices
@@ -64,469 +65,132 @@ Before you begin, make sure you have:
- Open KOReader from your apps menu - Open KOReader from your apps menu
- Enable Wi-Fi in the network settings - Enable Wi-Fi in the network settings
## Device Registration ## Connecting KOReader to Bookhoard
### Step 1: Get Your Bookhoard Instance URL Setup is done **on the server**: you approve the device from the Bookhoard web interface — no usernames, passwords, or tokens to type on the device.
Find your Bookhoard instance URL. This will typically be one of: ### Step 1: Install the Bookhoard Plugin
- **Local Network**: `http://YOUR_COMPUTER_IP:8765` 1. Clone the [Bookhoard KOReader plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
- **Localhost (if testing)**: `http://localhost:8765` 2. Copy it to your KOReader `plugins/` directory
- **Domain (if configured)**: `https://bookhoard.yourdomain.com` 3. Restart KOReader
### Step 2: Register Your Device in Bookhoard ### Step 2: Point the Plugin at Your Server
1. Log in to your Bookhoard web interface 1. Open KOReader, tap the **wrench icon** at the top
2. Navigate to **Device Management** → **Add New Device** 2. Find and tap **Bookhoard sync**
3. Fill in the device details: 3. Tap **Server URL**, enter your server address, then tap **OK**:
- **Device Name**: A friendly name (e.g., "My Kindle Paperwhite")
- **Device Type**: Select "KOReader"
- **Device Identifier**: Enter your device's hardware ID or serial number
- On Kindle: Settings → Device Options → Device Info → Serial Number
- On Kobo: Settings → Device Information → Serial Number
4. Click **Register Device**
You'll receive:
- An **Auth URL** to approve the device
- A **Device Token** (automatically generated after approval)
### Step 3: Approve Your Device
1. **Method A: QR Code**
- If displayed, scan the QR code with your phone's camera
- This will open the approval page in your browser
- Log in and click **Approve**
2. **Method B: Manual URL**
- Copy the Auth URL from the registration confirmation
- Open it in your web browser
- Log in to your Bookhoard account
- Click **Approve Device**
Your device is now registered and ready to sync!
## Configure KOReader Sync
### Step 1: Access KOReader Settings
1. Open KOReader on your device
2. Tap the menu icon (≡) in the top-left corner
3. Select **Tools** → **Calibre**
### Step 2: Configure Wireless Connection
1. **Enable Calibre Wireless Connection**: Toggle ON
2. **Server Address**: Enter your Bookhoard instance URL
``` ```
http://YOUR_COMPUTER_IP:8765/api/sync/koreader http://YOUR_COMPUTER_IP:8765
``` ```
Replace `YOUR_COMPUTER_IP` with your actual IP address Use your server's LAN IP (or domain if you have one configured).
3. **Set Custom Port** (if needed): Keep default or enter `8765` ### Step 3: Approve the Device in Bookhoard
### Step 3: Configure Authentication 1. On your computer or phone, open Bookhoard and go to **Settings → Devices**
2. Refresh the page — you'll see a **pending registration** for your device
3. Click **Approve** to connect the device
1. **Authentication Method**: Select "Basic Auth" Once approved, the plugin picks up its credentials automatically — reading progress sync and OPDS catalog access are set up automatically. No further configuration is needed.
2. **Username**: Your Bookhoard email or username
3. **Password**: Your Bookhoard password
### Step 4: Configure Sync Settings > **Note:** Pending registrations expire after 5 minutes. If yours expires, just re-run the sync from the plugin menu and approve again.
1. **Auto Sync**: Enable for automatic sync ### Auth Token (Advanced)
2. **Sync Frequency**: Choose from:
- Every page turn (recommended for real-time sync)
- Every bookmark save
- Every highlight
- Manual only (sync when you press the sync button)
3. **What to Sync**: Enable: The Devices page shows each KOReader device's **Auth Token**. You normally never need it (the plugin receives it automatically during approval), but it can be re-entered manually in the plugin settings if you're moving a setup between devices or debugging.
- ✅ Reading progress
- ✅ Bookmarks
- ✅ Highlights
- ✅ Notes
### Step 5: Test Connection ## What Syncs
1. Tap **Test Connection** in the Calibre settings Once connected, the following sync automatically in both directions between KOReader and Bookhoard (web and other devices):
2. You should see a success message if configured correctly
3. If it fails:
- Verify your device is connected to Wi-Fi
- Check the server URL is correct
- Ensure your Bookhoard instance is running
- Verify username and password are correct
## Using Sync Features - **Reading position** — percentage, chapter, and EPUB CFI where available
- **Bookmarks**
- **Highlights** — including highlight colors, mapped between the web and KOReader palettes
- **Notes** — standalone and attached to highlights
### Initial Sync Books are matched automatically using UUIDs, file hashes (SHA-256, format-aware so converted files still match), file aliases, and title/author fallback. If a book can't be matched, it shows up under the device's **Unlinked Books** in Bookhoard, where you can link it manually.
When you first enable sync, KOReader will:
1. Connect to Bookhoard
2. Upload your current reading progress
3. Download any annotations from the server
4. Set up bidirectional sync for future changes
### Reading Progress Sync
As you read:
- Progress updates automatically sync based on your sync frequency
- Page turns, chapter changes, and bookmark saves all trigger sync
- Sync occurs in the background without interrupting reading
### Annotations Sync
- **Bookmarks**: Sync when created or deleted
- **Highlights**: Sync when created, edited, or deleted
- **Notes**: Sync when created, edited, or deleted
- **Linked Notes**: Notes attached to highlights sync together
### Manual Sync
To manually trigger a sync:
1. Open the KOReader menu (≡)
2. Select **Tools** → **Calibre**
3. Tap **Sync Now**
The sync status will display:
- 🟢 **Synced** - All changes uploaded
- 🟡 **Syncing...** - In progress
- 🔴 **Failed** - Check your network connection
## Advanced Configuration
### Offline Mode
KOReader automatically handles offline scenarios:
1. Changes are queued locally when offline
2. Auto-sync resumes when connected
3. Queue processes all pending changes in priority order
### Checkpoint Sync
For better battery life, use checkpoint mode:
1. In KOReader Calibre settings
2. Set **Sync Mode** to "Checkpoint"
3. Set **Checkpoint Interval** (e.g., every 5 minutes)
4. Syncs occur in batches instead of every action
### Debug Mode
Enable debug logging if sync isn't working:
1. KOReader menu → Tools → Calibre
2. Enable **Debug Logging**
3. Sync and check logs at `/mnt/us/koreader/calibre.log`
## OPDS Wireless Book Delivery ## OPDS Wireless Book Delivery
### What is OPDS? Once your device is approved, the plugin also registers Bookhoard's OPDS catalog, so you can browse and download books wirelessly — no USB cable needed.
OPDS (Open Publication Distribution System) allows your KOReader device to **wirelessly download books** from Bookhoard - no USB cable needed!
### OPDS Benefits
- **Wireless Downloads**: Browse and download books over Wi-Fi
- **On-Demand Access**: Your entire library at your fingertips
- **Collection Support**: Browse and download from specific collections
- **Automatic Progress Sync**: Downloaded books sync progress instantly
- **Format Support**: EPUB, KEPUB, PDF, and more
### Enable OPDS in KOReader
#### Step 1: Get Your OPDS URL
1. Log in to Bookhoard web interface
2. Go to **Device Management**
3. Find your registered KOReader device
4. Click **Show OPDS URL**
5. Copy the URL (format: `http://YOUR_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog`)
#### Step 2: Add OPDS Catalog in KOReader
1. Open KOReader on your device
2. Tap the **+** (plus) button on the home screen
3. Select **OPDS Catalog**
4. Enter catalog details:
- **Name**: Bookhoard (or any name you prefer)
- **URL**: Paste your OPDS URL from Step 1
5. Tap **Save**
Your Bookhoard library now appears in KOReader's home screen!
### Browse and Download Books ### Browse and Download Books
#### Browse Your Library 1. In KOReader, open the OPDS catalog list and tap **Bookhoard**
2. Browse your library: all books, collections, and recent additions
3. Tap a book to see details and **Download** it
1. Tap **Bookhoard** on KOReader home screen ### Supported Formats
2. You'll see:
- **All Books**: Complete library view
- **Collections**: Books organized by collections
- **Recent**: Latest additions
3. Tap any category to browse
#### Download a Book
1. Browse to find a book
2. Tap the book to see details
3. Tap **Download**
4. Progress bar shows download status
5. Book opens automatically when complete
#### Download Entire Collections
1. In Bookhoard catalog, tap **Collections**
2. Select a collection
3. Tap **Download All** to get all books
4. Downloads queue and process in background
### OPDS Features
#### Supported Formats
KOReader OPDS supports:
- **EPUB**: Standard ebook format - **EPUB**: Standard ebook format
- **KEPUB**: Kobo-optimized format (KOReader handles this well) - **KEPUB**: Kobo-optimized format
- **PDF**: Fixed-layout documents - **PDF**: Fixed-layout documents
- **CBZ**: Comic book archives - **CBZ**: Comic book archives
- **TXT**: Plain text files
- **RTF**: Rich text format
#### Automatic Book Matching Books downloaded via OPDS are automatically matched to your library, so their progress syncs from the first page.
Books downloaded via OPDS are automatically matched:
- Uses SHA-256 hashes for precise matching
- Falls back to title/author matching
- Links to your existing Bookhoard library
- Progress syncs automatically
#### Collection Integration
Your Bookhoard collections appear in KOReader:
- Collection **"To Read"** → KOReader category
- Collection **"Science Fiction"** → Browseable section
- Custom collections → Preserved organization
### KOReader OPDS Settings
#### Update Interval
Configure how often KOReader checks for new books:
1. KOReader menu → Tools → OPDS
2. Set **Update Interval**: 5min, 15min, 1hr, manual
3. **Recommended**: 15min for balance
#### Download Location
Choose where to store downloaded books:
1. KOReader menu → File Browser
2. Set **Default Download Folder**
3. **Recommended**: `/mnt/us/Documents/` (Kindle) or `/mnt/onboard/Documents/` (Kobo)
#### Auto-Download
Automatically download new books from collections:
1. KOReader menu → Tools → OPDS
2. Enable **Auto-Download New Books**
3. Select collections to monitor
4. New books download automatically when connected to Wi-Fi
### OPDS Troubleshooting
#### Catalog Not Loading
**Problem**: Bookhoard catalog shows error or won't load
**Solutions**:
1. Verify device is connected to Wi-Fi
2. Check OPDS URL is correct in settings
3. Try accessing OPDS URL in your browser
4. Ensure Bookhoard server is running
5. Check Bookhoard device is approved
#### Download Fails
**Problem**: Book download starts but fails
**Solutions**:
1. Check Wi-Fi signal strength
2. Ensure sufficient storage on device
3. Try downloading a smaller book
4. Check Bookhoard has the book file
5. Review Bookhoard logs for errors
#### Book Opens But Progress Doesn't Sync
**Problem**: Downloaded book doesn't sync progress
**Solutions**:
1. Verify book is matched to Bookhoard library
2. Check device sync settings are enabled
3. Try manual sync from device
4. Ensure book exists in Bookhoard with same hash
5. Check Bookhoard Progress page
#### Slow Downloads
**Problem**: Books take too long to download
**Solutions**:
1. Stay close to Wi-Fi router
2. Use 5GHz Wi-Fi if available
3. Close other apps using bandwidth
4. Download smaller books first
5. Consider USB for large books (100MB+)
### Advanced OPDS Configuration
#### Custom User-Agent
Some OPDS catalogs require specific user agent:
```lua
-- In KOReader settings
OPDSUserAgent = "KOReader/2024.01"
```
#### Authentication Token
If Bookhoard requires token authentication:
1. Get token from Bookhoard device settings
2. Add to OPDS URL: `?token=YOUR_TOKEN`
3. KOReader includes token in all requests
#### Compression
Enable compression for faster downloads:
```lua
-- In KOReader settings
OPDSCompressionEnabled = true
```
### OPDS vs USB Transfer
| Feature | OPDS (Wireless) | USB Transfer |
| ----------------- | ----------------------------- | ----------------------- |
| **Convenience** | ⭐⭐⭐⭐⭐ No cable needed | ⭐⭐ Requires cable |
| **Speed** | ⭐⭐⭐ Fast (Wi-Fi dependent) | ⭐⭐⭐⭐⭐ Very fast |
| **Bulk Transfer** | ⭐⭐⭐ One at a time | ⭐⭐⭐⭐⭐ Many at once |
| **Progress Sync** | ⭐⭐⭐⭐⭐ Instant | ⭐⭐⭐⭐ After transfer |
| **Accessibility** | ⭐⭐⭐⭐⭐ Anywhere | ⭐⭐ At computer only |
| **Reliability** | ⭐⭐⭐⭐ Very good | ⭐⭐⭐⭐⭐ Excellent |
**Recommendation**: Use OPDS for daily reading (convenience), USB for bulk library transfers.
### OPDS Tips and Tricks
1. **Favorite Collections**: Pin frequently-used collections to home screen
2. **Batch Downloads**: Start multiple downloads before leaving Wi-Fi
3. **Download Queue**: Downloads continue in background while reading
4. **Storage Management**: Check free space before downloading large collections
5. **Network Speed**: Use 5GHz Wi-Fi for faster downloads if available
## Troubleshooting ## Troubleshooting
### Pending Registration Never Appears
**Problem**: You entered the Server URL, but no pending registration shows in Bookhoard
**Solutions**:
1. Verify the Server URL is correct (no trailing path — just the base address)
2. Make sure KOReader is connected to Wi-Fi
3. Check the Bookhoard server is reachable from the device's network
4. Registrations expire after 5 minutes — re-run the sync and approve quickly
### Connection Refused ### Connection Refused
**Problem**: "Connection refused" error **Problem**: "Connection refused" error on the device
**Solutions**: **Solutions**:
- Verify Bookhoard is running on your computer - Verify Bookhoard is running
- Check the server URL and port (8765) - Check the server address and port (default `8765`)
- Ensure device is on same Wi-Fi network - Ensure the device is on the same Wi-Fi network as the server
- Try using your computer's IP address instead of "localhost" - Use the server's LAN IP instead of `localhost`
### Authentication Failed ### Sync Not Working After Approval
**Problem**: "Authentication failed" error **Problem**: Device shows as approved but changes don't appear in Bookhoard
**Solutions**: **Solutions**:
- Verify username and password - Trigger a manual sync from the plugin menu
- Check your account is active and not locked - Check the device shows as enabled in **Settings → Devices**
- Try logging in to Bookhoard web interface first - Verify the book appears in the device's Unlinked Books and link it if needed
- Reset password if needed - Check Bookhoard server logs for errors
### Sync Not Working
**Problem**: Changes not appearing in Bookhoard
**Solutions**:
- Enable debug logging in KOReader
- Check Bookhoard Device Management page for errors
- Verify sync is enabled in KOReader settings
- Try manual sync to trigger immediate update
- Check Bookhoard logs for sync errors
### Conflicts Detected ### Conflicts Detected
**Problem**: Sync conflicts when reading on multiple devices **Problem**: Sync conflicts when reading the same book on multiple devices
**Solutions**: **Solutions**:
1. Go to Bookhoard **Conflicts** page 1. Go to Bookhoard's **Conflicts** page
2. Review conflicting progress from each device 2. Review the progress reported by each device
3. Choose which device's progress to keep 3. Choose which device's progress to keep
4. Set auto-resolution preference for future conflicts
### Large Files Not Syncing
**Problem**: Large annotations or highlights fail to sync
**Solutions**:
- Check Bookhoard sync queue for stuck items
- Increase sync timeout in KOReader settings
- Break up large highlights into smaller segments
- Verify network bandwidth is sufficient
## Security Best Practices ## Security Best Practices
1. **Use HTTPS**: If deploying Bookhoard publicly, configure SSL/TLS 1. **Use HTTPS**: If exposing Bookhoard beyond your LAN, configure SSL/TLS
2. **Strong Password**: Use a secure password for your Bookhoard account 2. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3) 3. **Device Authorization**: Only approve pending registrations you initiated
4. **Device Authorization**: Only approve devices you recognize 4. **Revoke lost devices**: Remove devices you no longer use from the Devices page
5. **Regular Updates**: Keep KOReader updated to the latest version
## Additional Resources ## Additional Resources
- [KOReader Documentation](https://github.com/koreader/koreader) - [KOReader Documentation](https://github.com/koreader/koreader)
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271) - [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
- [Bookhoard Universal Sync Guide](../sync-guide.md) - [Bookhoard Universal Sync Guide](../sync-guide.md)
- [Kobo Setup Guide](kobo-setup.md) - [Bookhoard KOReader Plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
## Support
If you encounter issues:
1. Check the troubleshooting section above
2. Enable debug logging and review KOReader logs
3. Check Bookhoard sync queue and device management pages
4. Open an issue on the Bookhoard GitHub repository
--- ---
**Last Updated**: 2026-01-31 **Last Updated**: August 2026
**Bookhoard Version**: 1.0 **Bookhoard Version**: 1.0
**KOReader Version**: 2024.01+