Files
eleith 0ca37ee031
ci/woodpecker/tag/build-docker Pipeline was successful
[docs] cleanup
2026-10-01 09:13:14 -07:00

143 lines
4.3 KiB
Markdown

# readeckobo
This tool acts as an Instapaper proxy, so your Kobo can sync with your
[Readeck](https://readeck.com) articles.
This started as a Go port of [kobeck](https://github.com/Lukas0907/kobeck), and
then evolved to support multiple users, logging, performance improvements, ebook
syncing pass through and more.
## ✨ Features
* 🗞️ Syncs non-archived articles from Readeck to Kobo
* 📑 Downloads article content and image for each bookmark
* 📋️ Supports archiving, re-adding, favoriting, and deleting
* 📷️ Converts images to JPEG format for e-reader compatibility
* 👥 Supports multiple Kobo devices and readeck accounts
* 📚 Supports passthrough ebook library syncing (ex: Komga)
## 🚀 Quick Start (for Users)
### 1. Choose how you will deploy
Choose a public HTTPS hostname (for example, `readeckobo.example.com`) and one
deployment method:
* [Cloudflare Tunnel](docs/CLOUDFLARE.md): forward requests to `readeckobo`.
* [Nginx](docs/NGINX.md): proxy Kobo Store and article requests.
### 2. Generate a device token
Copy `config.yaml.example` to `config.yaml`, then build the image. Find your
Kobo's serial number under **Settings -> Device Information**. Replace
`<YOUR_KOBO_SERIAL>` below with that number (without angle brackets):
```sh
docker-compose build
docker-compose run --rm --entrypoint /app/bin/generate-encrypted-token.sh readeckobo <YOUR_KOBO_SERIAL>
```
This will generate two strings:
* a plaintext token for a user in your `config.yaml`
* an encrypted token for Kobo
### 3. Configure `readeckobo` and Kobo
Edit `config.yaml` with your Readeck host and API token and the plaintext token
from step 2:
```yaml
server:
port: 8080
log_level: info
readeck:
host: "https://readeck.example.com"
users:
- token: "<THE-PLAIN-TEXT-TOKEN-FROM-THE-SCRIPT>"
readeck_access_token: "a-readeck-api-token"
```
For more config options, see [docs/CONFIG.md](docs/CONFIG.md). To sync ebooks in
addition to readeck articles (using an ebook library provider like Komga), see
the [Kobo ebook sync guide](docs/KOBO_SYNC.md).
Now, mount your Kobo and edit `.kobo/Kobo/Kobo eReader.conf`, using the encrypted
token. Replace `readeckobo.example.com` with the hostname you
chose in step 1:
```ini
[OneStoreServices]
api_endpoint=https://readeckobo.example.com/instapaper-proxy/storeapi
instapaper_env_url=https://readeckobo.example.com
[Instapaper]
AccessToken=@ByteArray(<THE-ENCRYPTED-TOKEN-FROM-THE-SCRIPT>)
```
### 4. Run the app
```sh
docker-compose up -d
```
The app is now available locally at `http://localhost:8080`
## 🔒 A Quick Word on Security
A little security goes a long way.
* **Use HTTPS:** follow either deployment guide above, and keep the app's HTTP
port private.
* **Protect tokens:** don't share config files or request URLs containing device
tokens. Browser login or bot challenges may prevent Kobo sync.
* **Kobo Password:** prevent unauthorized mounting with a Kobo password.
## 🧑‍💻 For Developers
### Building and Running Locally
```sh
# Build the docker image
docker-compose build
# Run the server
docker-compose up
```
The server will be available at `http://localhost:8080`.
### API Endpoints
`readeckobo` emulates the Instapaper API for Kobo devices. Here's a quick overview:
<!-- markdownlint-disable MD013 -->
| Endpoint | Description |
| -------------------------- | ----------- |
| `POST /api/kobo/get` | syncs non-archived articles from Readeck. |
| `POST /api/kobo/download` | downloads the content of an article for offline reading. |
| `POST /api/kobo/send` | handles archiving, favoriting, deleting, or adding new articles. |
| `GET /api/convert-image` | a helper endpoint to convert all article images to JPEG |
| `GET /booksync` | an optional proxy passthrough to a user's `book_sync_url` |
<!-- markdownlint-enable MD013 -->
### Testing
The `scripts/e2e-tests/` directory has simple shell scripts for testing each API
endpoint. They're great for checking if everything is working as expected.
```sh
# Run the 'get' test
./scripts/e2e-tests/01-test-get.sh <YOUR_DEVICE_TOKEN>
```
### Makefile Targets
The `Makefile` has some handy targets:
* `make build`: Build the application binary.
* `make test`: Run all unit tests.
* `make lint`: Run the linter.
* `make vendor`: Vendor all dependencies.
* `make ci`: Run all CI checks (linting and testing).