readeckobo

This tool acts as an Instapaper proxy, so your Kobo can sync with your Readeck articles.

This started as a Go port of kobeck, and then evolved to support multiple users, logging, performance improvements 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

🚀 Quick Start (for Users)

Getting up and running is a breeze with Docker.

1. Configure readeckobo

First, copy config.yaml.example to config.yaml and edit it to match your setup.

For a detailed explanation of all options and how to get your Readeck API token, see docs/CONFIG.md.

server:port:8080log_level:inforeadeck:host:"https://your-readeck-instance.com"users:- token:"a-random-uuid-token-for-a-kobo"readeck_access_token:"a-readeck-api-token"

2. Run with Docker

Once your configuration is ready, fire it up!

docker-compose build
docker-compose up -d

The server will be available at http://localhost:8080.

3. Generate a Device Token

For each Kobo device, you will need a unique token. This process involves generating a token and then encrypting it for the Kobo device.

First, find your Kobo's serial number, which is available under Settings -> Device Information on your e-reader.

With readeckobo running, use this command to generate and encrypt the token, replacing <YOUR_KOBO_SERIAL> with your device's serial number:

docker-compose exec readeckobo bin/generate-encrypted-token.sh <YOUR_KOBO_SERIAL>

The script will output two important pieces of information:

1. A plain text UUID token to be used in your config.yaml.
2. An encrypted token to be used in your Kobo's configuration file.

4. Configure Your readeckobo and Kobo Device

Follow the output from the script to configure your services.

1. Update config.yaml: Add the plain text UUID token to the users section of your config.yaml.

   users:- token:"<THE-PLAIN-TEXT-UUID-FROM-THE-SCRIPT>"readeck_access_token:"a-readeck-api-token"

2. Update Your Kobo: Mount your Kobo and find the .kobo/Kobo/Kobo eReader.conf file. Add or update these settings using the encrypted token from the script's output.

   [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>)
   

Replace https://readeckobo.example.com with the full path to where you are deploying the readeckobo service to

5. Set Up a Reverse Proxy

readeckobo must be run behind a reverse proxy to handle HTTPS. It's crucial to proxy three specific location blocks, as shown in our nginx.conf.snippet example.

Your Kobo device periodically re-syncs its configuration from Kobo's servers, which can overwrite your custom Instapaper endpoint. The proxy rules below ensure this connection is preserved.

Without these rules, your Kobo will eventually lose its connection to readeckobo.

🔒 A Quick Word on Security

A little security goes a long way.

• Use HTTPS: deploy behind a reverse proxy that provides HTTPS
• Stay Local: Keep it on your local private network
• Kobo Password: prevent unauthorized mounting with a Kobo password

🧑‍💻 For Developers

Building and Running Locally

# 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:

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.

# 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).