edouard.paris / crosspoint-reader
A fork of https://github.com/crosspoint-reader/crosspoint-reader
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: add quick KOReader sync setup guide (#1181)

## Summary

* **What is the goal of this PR?**
Improve KOReader Sync documentation so new users can self-host and
configure sync quickly, with clear references in both README and
USER_GUIDE.

* **What changes are included?**
- Add a KOReader Sync feature mention in `README.md` and link to a
quick-setup section in the guide.
- Add `3.6.5 KOReader Sync Quick Setup` to `USER_GUIDE.md` with:
- Docker Compose-first setup instructions (plus Podman compose
alternative)
- healthcheck verification
- one-time user registration example using `curl`
- device-side setup steps (`Settings -> System -> KOReader Sync` and
`Authenticate`)
- in-reader usage via `Sync Progress` in the reader menu
- Update reading mode navigation wording from "Chapter Menu" to "Reader
Menu" so it reflects current UI behavior.

Closes #1032.

## Additional Context

* This is documentation-only and does not change firmware behavior.
* The quick-setup flow is intentionally short and focused on getting
sync working quickly for typical home-network setups.

---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? _**YES**_

authored by

Willy Hardy and committed by
GitHub 4fb785af 74c72059

+111 -1
+3 -1
README.md
··· 36 36 - [x] Cover sleep screen 37 37 - [x] Wifi book upload 38 38 - [x] Wifi OTA updates 39 + - [x] KOReader Sync integration for cross-device reading progress 39 40 - [x] Configurable font, layout, and display options 40 41 - [ ] User provided fonts 41 42 - [ ] Full UTF support ··· 43 44 44 45 Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](./USER_GUIDE.md#supported-languages). 45 46 46 - See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint. 47 + See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint, including the 48 + [KOReader Sync quick setup](./USER_GUIDE.md#365-koreader-sync-quick-setup). 47 49 48 50 For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document. 49 51
+108
USER_GUIDE.md
··· 20 20 - [3.6.2 Reader](#362-reader) 21 21 - [3.6.3 Controls](#363-controls) 22 22 - [3.6.4 System](#364-system) 23 + - [3.6.5 KOReader Sync Quick Setup](#365-koreader-sync-quick-setup) 23 24 - [3.7 Sleep Screen](#37-sleep-screen) 24 25 - [4. Reading Mode](#4-reading-mode) 25 26 - [Page Turning](#page-turning) ··· 196 197 - **Clear Reading Cache**: Clear the internal SD card cache. 197 198 - **Check for updates**: Check for Crosspoint firmware updates over WiFi. 198 199 - **Language**: Set the system language (see **[Supported Languages](#supported-languages)** for more information). 200 + 201 + #### 3.6.5 KOReader Sync Quick Setup 202 + 203 + CrossPoint can sync reading progress with KOReader-compatible sync servers. 204 + It also interoperates with KOReader apps/devices when they use the same server and credentials. 205 + 206 + ##### Option A: Free Public Server (`sync.koreader.rocks`) 207 + 208 + 1. Register a user once (only if needed): 209 + 210 + ```bash 211 + USERNAME="user" 212 + PASSWORD="pass" 213 + PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')" 214 + 215 + curl -i "https://sync.koreader.rocks/users/create" \ 216 + -H "Accept: application/vnd.koreader.v1+json" \ 217 + -H "Content-Type: application/json" \ 218 + --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}" 219 + ``` 220 + 221 + Already have KOReader Sync credentials? Skip registration; basic sync only requires using the same existing username/password on all devices. 222 + 223 + When this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, pick a different username or use that existing account. 224 + 225 + 2. On each CrossPoint device: 226 + - Go to **Settings -> System -> KOReader Sync**. 227 + - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices). 228 + - Set **Sync Server URL** to `https://sync.koreader.rocks`, or leave it empty (both use the same default KOReader sync server). 229 + - Run **Authenticate**. 230 + 231 + 3. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**. 232 + - Choose **Apply Remote** to jump to remote progress. 233 + - Choose **Upload Local** to push current progress. 234 + 235 + ##### Option B: Self-Hosted Server (Docker Compose) 236 + 237 + 1. Start a sync server: 238 + 239 + ```bash 240 + mkdir -p kosync-quickstart 241 + cd kosync-quickstart 242 + 243 + cat > compose.yaml <<'YAML' 244 + services: 245 + kosync: 246 + image: koreader/kosync:latest 247 + ports: 248 + - "7200:7200" 249 + - "17200:17200" 250 + volumes: 251 + - ./data/redis:/var/lib/redis 252 + environment: 253 + - ENABLE_USER_REGISTRATION=true 254 + restart: unless-stopped 255 + YAML 256 + 257 + # Docker 258 + docker compose up -d 259 + 260 + # Podman (alternative) 261 + podman compose up -d 262 + ``` 263 + 264 + > [!NOTE] 265 + > `ENABLE_USER_REGISTRATION=true` is convenient for first setup. After creating your users, set it to `false` (or remove it) to avoid unexpected registrations. 266 + 267 + 2. Verify the server: 268 + 269 + ```bash 270 + curl -H "Accept: application/vnd.koreader.v1+json" "http://<server-ip>:17200/healthcheck" 271 + # Expected: {"state":"OK"} 272 + ``` 273 + 274 + 3. Register a user once. 275 + CrossPoint authenticates against KOReader Sync (`koreader/kosync`) using an MD5 key, so register using the MD5 of your password: 276 + 277 + > [!WARNING] 278 + > Sending a reusable MD5-derived password over plain HTTP is insecure. 279 + > Create unique sync-only credentials and do not reuse main account passwords. 280 + > Prefer `https://<server-ip>:7200` whenever traffic leaves a fully trusted LAN or when using untrusted networks. 281 + > Use `curl -k` only for self-signed certificate testing. 282 + 283 + ```bash 284 + USERNAME="user" 285 + PASSWORD="pass" 286 + PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')" 287 + 288 + curl -i "http://<server-ip>:17200/users/create" \ 289 + -H "Accept: application/vnd.koreader.v1+json" \ 290 + -H "Content-Type: application/json" \ 291 + --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}" 292 + ``` 293 + 294 + If this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, the account already exists. 295 + 296 + 4. On each CrossPoint device: 297 + - Go to **Settings -> System -> KOReader Sync**. 298 + - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices). 299 + - Set **Sync Server URL** to `http://<server-ip>:17200`. 300 + - Run **Authenticate**. 301 + 302 + If you use the HTTPS listener, use `https://<server-ip>:7200` (`curl -k` only for self-signed certificate testing). 303 + 304 + 5. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**. 305 + - Choose **Apply Remote** to jump to remote progress. 306 + - Choose **Upload Local** to push current progress. 199 307 200 308 ### 3.7 Sleep Screen 201 309