Prosa-Kobo (0.1.0)

Prosa-Kobo is a middleware layer that translates requests from a Kobo device into Prosa requests and responses from Prosa into Kobo-compatible responses. With it, you can connect any Kobo device to your Prosa backend.

Each Kobo device that contacts the middleware can be associated with a Prosa API key.
When a device is linked to an API key, all of its requests are translated into Prosa API calls, and the responses are converted back into Kobo-compatible responses before being returned to the device.

This middleware completely replaces the official Kobo backend, no requests are proxied to Kobo’s original servers.

Prosa-Kobo can be configured in two ways:

1. Configuration files (TOML)
2. Environment variables

The configuration system is layered, meaning defaults are loaded first and then overridden by local configuration or environment variables.

Prosa-Kobo comes with built-in default configurations that are embedded directly into the binary.

The following example shows the default configuration values.
You can override these defaults by providing your own configuration file.

Example (Default) Configuration

[server.bind]
host = "0.0.0.0"
port = 5001

# Uncomment if behind a proxy

# [server.public]
# scheme = "http"
# host = "192.168.0.1"
# port = 5001

[database]
file_path = "persistence/database.db"

[auth]
jwt_key_path = "persistence/jwt_secret_key.bin"
token_duration = 900
refresh_token_duration = 3600

[prosa]
scheme = "http"
host = "127.0.0.1"
port = 5000

[download_token]
book_expiration = 60

Any value from the default configuration can be overridden by creating a local configuration file.

By default, Prosa-Kobo looks for ./configuration.toml.

You can change this path using the CONFIGURATION environment variable.
Values defined in configuration.toml will override the default values.

All configuration values can also be controlled directly through environment variables.
The format is <SECTION>__<KEY>.

• Sections map to the [section] headers in the TOML file.

• Keys map to the field names inside each section.

Important:

• Sections and keys are separated using double underscores (__).

• Single underscores (_) inside a key name (e.g. file_path) remain as-is and are not separators.

For example:

• To set the server port ([server.bind].port):

  export SERVER__BIND__PORT=8080
  

• To set the database file path ([database].file_path):
  (notice there is only one underscore between FILE and PATH because the field name itself has an underscore)

  export DATABASE__FILE_PATH=database/database.db
  

• [server.bind]

  • host: Network interface where the middleware server will listen.

  • port: Port number the middleware server will listen on.

• [server.public] (required if running behind a proxy)

  • scheme: Scheme (http or https) used when generating URLs returned to clients.

  • host: Public hostname or IP address clients use to reach the middleware.

  • port: Public port number clients use to reach the middleware.

  These settings are necessary when the middleware is running behind a proxy, because the real client-facing address cannot be detected automatically.
  If the middleware is not behind a proxy, this section can be omitted, and values will be detected automatically.

• [database]

  • file_path: Path to the SQLite database file.

• [auth]

  • jwt_key_path: Path to the file that will store the JWT HMAC signing key.
  • token_duration: Expiration duration (seconds) for JWT tokens provided to Kobo devices.
  • refresh_token_duration: Expiration duration (seconds) for refresh tokens provided to Kobo devices.

• [prosa]

  • scheme: Scheme (http or https) used to connect to the Prosa backend.
  • host: Hostname or IP address of the Prosa server.
  • port: Port number of the Prosa server.

• [download_token]

  • book_expiration: Duration (seconds) of the validity of download tokens for books.

    Kobo devices cannot use JWT authentication for book downloads, so the middleware generates temporary download tokens that authenticate devices for retrieving books.

You can control the logging level using the standard RUST_LOG environment variable.
Supported values include error, warn, info, debug, and trace.

• Default:

  RUST_LOG=info
  

• Example (set log level to warn):

  export RUST_LOG=warn
  

Prosa-Kobo can be run either as a Docker container (recommended) or as a standalone binary.

The simplest way to get Prosa-Kobo running alongside Prosa is using Docker. Below is an example compose.yaml configuration that runs both services together:

services:
  prosa-kobo:
    image: tsousa28/prosa-kobo
    container_name: prosa-kobo
    ports:
      - "5001:5001"
    environment:
      - PROSA__HOST=prosa
      - PROSA__PORT=5000
    volumes:
      - prosa_kobo:/app/persistence
    restart: unless-stopped

  prosa:
    image: tsousa28/prosa
    container_name: prosa
    ports:
      - "5000:5000"
    environment:
      - AUTH__ADMIN_KEY=very_secret_key
    volumes:
      - prosa_library:/app/library
    restart: unless-stopped

volumes:
  prosa_kobo:
  prosa_library:  

This will start both Prosa and Prosa-Kobo, making Prosa available on port 5000 and Prosa-Kobo on port 5001.
Kobo devices should connect to port 5001 for all requests.

Important notes:

• Don't forget to set AUTH__ADMIN_KEY to a secure value before using Prosa.

• Persistence requires named volumes mounted at /app/persistence for Prosa-Kobo and /app/library for Prosa. Bind mounts are currently not supported due to permission issues in rootless containers.

• Environment variables that change internal paths are ignored in these container images.

If you prefer running Prosa-Kobo as a binary:

1. Set up Prosa
   Make sure Prosa is installed and running. You can follow the official guide: Prosa Installation and Setup.

2. Configure Prosa-Kobo
   Adjust the Prosa-Kobo configuration file as needed. For full details, see the Configuration Reference.

3. Run the Middleware
   Launch the Prosa-Kobo binary. Kobo devices should now connect to the middleware, which will handle requests and translate them to and from Prosa.

1. Point Your Kobo Device to Prosa-Kobo
   On your Kobo device, edit the .kobo/Kobo/Kobo eReader.conf file and change the api_endpoint value to the Prosa-Kobo server’s host.

2. Attempt a Sync
   Try syncing the device. The first attempt will fail since the device is not yet linked.

3. Check for Unlinked Devices
   Retrieve the device ID using the List Unlinked Devices endpoint.

4. Link the Device
   Link the device to a Prosa API key with the Link Device endpoint.

Important Note on Sync Issues
Sometimes, even after linking a device, sync may still fail. This happens because Kobo devices do not immediately invalidate their old OAuth tokens, even when receiving a 403 or 401 response.

• If this occurs, simply wait. The old token will expire within 1 hour.
• To avoid this issue entirely, make sure you do not sync or connect to the internet before changing the endpoint on your device.

You’re now ready to sync your Kobo device with Prosa through Prosa-Kobo!