Skip to content

Commit 8ea4e05

Browse files
amarderamarder
authored
Merge pull request #91 from amarder/feature/kindle
Feature/kindle
2 parents 8271c71 + 0c8c1df commit 8ea4e05

1 file changed

Lines changed: 126 additions & 0 deletions

File tree

‎src/content/post/kindle.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: "WinterBreak: Unlocking Kindle's Full Potential"
3+
description: 'How I set up KOReader on my Kindle and phone, with books synced across both devices via Calibre-Web and OPDS.'
4+
publishDate: '2026-04-01'
5+
---
6+
7+
Oops!... I did it again! I went down another rabbit hole. This time I jailbroke my Kindle using [WinterBreak](https://kindlemodding.org/jailbreaking/WinterBreak/). Why did I do this?
8+
9+
- Over the weekend, I was reading a book on my Kindle and wanted to switch to reading on my phone. Jailbreaking would make that easier.
10+
- I wanted to try out [KOReader](https://koreader.rocks/), which I've heard great things about.
11+
- I have an extra Kindle lying around that I want to turn into a [TRMNL](https://trmnl.com/guides/turn-your-amazon-kindle-into-a-trmnl) eventually.
12+
13+
## My Setup
14+
15+
Below is a diagram of my setup. I manage e-books in Calibre on my laptop, then use Syncthing to automatically copy those files to my home server. From there, Calibre-Web serves them to my Kindle, phone, and other devices.
16+
17+
```mermaid
18+
graph LR;
19+
subgraph "Laptop"
20+
Calibre["Calibre"];
21+
end
22+
23+
subgraph "Home Server"
24+
CalibreWeb["Calibre-Web"];
25+
end
26+
27+
subgraph "Phone"
28+
PhoneKO["KOReader"];
29+
end
30+
31+
subgraph "Kindle"
32+
KindleKO["KOReader"];
33+
end
34+
35+
Calibre -- "Syncthing" --> CalibreWeb;
36+
CalibreWeb -- "OPDS" --> KindleKO;
37+
CalibreWeb -- "OPDS" --> PhoneKO;
38+
```
39+
40+
The workflow is simple:
41+
42+
1. Add or update a book in Calibre on my laptop
43+
2. Syncthing syncs the change to the home server
44+
3. On whichever device I want to read, open KOReader's OPDS browser, find the book, and download it
45+
46+
### Calibre
47+
48+
I've been using [Calibre](https://calibre-ebook.com/) on my laptop to manage e-books for years. It's excellent: I use it to organize my library, convert formats, and fetch metadata.
49+
50+
### Syncthing
51+
52+
[Syncthing](https://syncthing.net/) runs as a background service on both my laptop and my home server. I pointed it at my Calibre library folder and let it do its thing. It's reliable and completely automatic: whenever I add or update a book in Calibre, Syncthing pushes the changes to the server within seconds.
53+
54+
One thing to be mindful of: Calibre and Calibre-Web share the same `metadata.db` file. To avoid corruption, Calibre-Web mounts the library as read-only, so only Calibre on the laptop ever writes to the database.
55+
56+
### Calibre-Web
57+
58+
[Calibre-Web](https://github.com/janeczku/calibre-web) is a web application that sits in front of a Calibre library and serves it over HTTP. It has a web UI for browsing books, and more importantly for my purposes, it exposes an [OPDS](https://opds.io/) catalog.
59+
60+
OPDS is a standard for serving catalogs of books over HTTP. KOReader has a built-in OPDS browser that can connect to any OPDS server, browse the catalog, and download books directly to the device. Once Calibre-Web was running, I added it as an OPDS source in KOReader, and my entire library became available.
61+
62+
Calibre-Web runs on my home server with Docker Compose:
63+
64+
```yaml
65+
services:
66+
calibre-web:
67+
image: lscr.io/linuxserver/calibre-web:latest
68+
volumes:
69+
- /path/to/calibre/library:/books:ro
70+
- calibre-web-config:/config
71+
ports:
72+
- "8083:8083"
73+
74+
volumes:
75+
calibre-web-config:
76+
```
77+
78+
The default credentials for Calibre-Web are meant to be changed:
79+
80+
```yaml
81+
username: admin
82+
password: admin123
83+
```
84+
85+
### KOReader
86+
87+
On both the Kindle and the phone, I configured KOReader's OPDS browser. In the file browser (this isn't available when a book is open), tap the magnifying glass icon, select OPDS, and add a new entry pointing to `http://<server>:8083/opds`. After that, my entire Calibre library was available to browse and download. KOReader's OPDS browser is a little clunky, but it works fine.
88+
89+
## Usage Notes
90+
91+
### Highlights
92+
93+
[Readwise](https://readwise.io/) is a popular service for aggregating highlights from many sources, including KOReader, into a single searchable library, but at $10/month it's more than I want to pay.
94+
95+
KOReader offers an "Export highlights" feature (`Tools > Export highlights`) that lets you save your highlights as Markdown files. I plan to export my highlights and manage them in [Obsidian](https://obsidian.md/). It's a manual step. I trigger the export and move the file into my knowledge base, but it's straightforward and free.
96+
97+
### Progress Sync
98+
99+
KOReader also includes a "Progress sync" feature that can sync your reading position to a remote server using the `kosync` protocol. I spun up [koreader-sync-server](https://github.com/koreader/koreader-sync-server) to try it out, but ultimately decided it wasn't worth the extra complexity for me. I rarely switch mid-book between devices, so I just use the OPDS browser to grab the book I want and manually find my spot.
100+
101+
## Jailbreaking
102+
103+
For the most part, the WinterBreak instructions are quite good. I ran into two issues while installing KUAL (Kindle Unified Application Launcher) and MRPI (MobileRead Package Installer).
104+
105+
The first time I typed `;log mrpi` into the search bar of my Kindle, it failed because there wasn't enough disk space for the installation. I needed to clear out about 1 GB.
106+
107+
The second time, the installation got further but still failed. I had Claude Sonnet read the log file and identify the problem.
108+
109+
```
110+
FAT-fs (loop0): error, fat_get_cluster: invalid cluster chain (i_pos 1285765)
111+
FAT-fs (loop0): Filesystem has been set read-only
112+
```
113+
114+
The Kindle's internal storage had a corrupted FAT filesystem. When MRPI tried to extract the KUAL package, the filesystem had already been forced into read-only mode, so the write failed and the installer quietly gave up. The fix was to run a filesystem check from my Mac with the Kindle connected over USB:
115+
116+
```bash
117+
diskutil unmount /dev/diskX
118+
sudo fsck_msdos -y /dev/diskX
119+
diskutil mount /dev/diskX
120+
```
121+
122+
`fsck_msdos` found and repaired the bad cluster chain, and after that, `;log mrpi` worked. Third time's the charm!
123+
124+
## Conclusion
125+
126+
Overall, I'm stoked about my new system. KOReader is super customizable, so I can tweak the look of my books exactly how I want. Now I can focus on actually reading (instead of tinkering)! 📚

0 commit comments

Comments
 (0)