WARNING
This feature is fairly new in Calibre-Web and has had limited testing: You will likely run into new issues if you try this out. I'd recommend waiting a little bit for this cautionary message do disappear if you aren't comfortable with some rough edges.
Known issues:
- #1276 : Syncing of large libraries may timeout and fail.
Also keep in mind that Kobo devices will not sync PDF formatted files.
Setup
As a prerequisite you need to install the dependencies listed in optional-requirements.txt under the Kobo integration section.
A simple way to do this is to move them to a kobo-requirements.txt file, then run the following for a pip install
./venv/bin/python3 -m pip install -r kobo-requirements.txt
Kobo integration must first be enabled in Calibre-Web by toggling ON the Enable Kobo sync checkbox in the Basic configuration >> Feature Configuration page. The user syncing the books to the kobo reader needs to have Downloads Allowed. If you are accessing your Calibre-Web instance from your Kobo via some sort of port-forwarding mechanism (e.g. your router maps port X to machine Y on port Z), please change the External Port setting to port X in this example (the external port). This necessary due to a bug in HTTP-requests the Kobo reader creates, and can't be avoided.
The Kobo eReader.conf file found under the .kobo/Kobo directory on Kobo devices is used to configure which URL the device uses for syncing books. By default, the config file contains the following row:
api_endpoint=https://storeapi.kobo.com
If the row does not exist it must be created under the [OneStoreServices] group.
Users can generate a URL to sync with Calibre-Web instead by clicking the Create/View button under their Calibre-Web profile page.
If you experience issues running calibre-web behind a proxy such as nginx, please see this issue
Sync only selected Shelfs to Kobo
There is a checkbox for setting the sync to only use specific shelf. If this is ticked new options are showing up on a per-user basis in the Edit Shelf section. For each shelf you can select if the books in it are synced to Kobo reader or not. If the checkbox is not ticked all books are synced to kobo reader. Caution: Syncing all books to kobo reader and then activating this checkbox will archive all books which are not part of a synced shelf after the next sync with your kobo reader.
Store purchases
If you want to maintain access to the official Kobo store on the device, you can set the Proxy unknown requests to Kobo Store checkbox. When syncing, we will try to sync against both the official Kobo Store as well as Calibre-Web's library.
Changing Kobo devices
If a user moves to a new Kobo device (such as when upgrading to new hardware) and keeps the same sync token, make sure to trigger Force full kobo sync in that user's settings. Without this, the sync to the new device will only include new books and those not already synced to the old device.
Privacy & Security caution
The Kobo device sends out a unique and irrevocable (even across password reset) {device_id; user_id} pair during the Sync protocol. If CalibreWeb is exposed over the internet without SSL, then this id pair could theoretically be stolen (if anyone was bothered to...). As far as I can tell, a malicious individual wouldn't be able to make account changes or purchases, but would be able to download the list of purchased or borrowed books, collections, reading stats, etc.
Optional: Installing a self signed certificate on Kobo
You can install a self-signed certificate on the device by copying a DER encoded certificate with a .cer file extension to the .kobo/certificates directory on the Kobo device. For example, to convert an existing certificate to the right format:
openssl x509 -in self-signed-cert.crt -outform DER -out /media/KOBOeReader/.kobo/certificates/calibre_web.cer
Feature support:
Book management
Adding books to Calibre/Calibre-Web will cause them to appear on the device the next time it Syncs with Calibre-Web.
Deleting a book from Calibre/Calibre-Web will not cause it to be removed from the device on the next Sync. In order to trigger deletions from their devices, users must archive books and then sync their devices.
Reading state and statistics
Book progress and reading statistics are synced with and stored in Calibre-Web. At the moment, Calibre-Web will only display whether books have been completed (Read) or not (Unread).
Troubleshooting
If you're having trouble with Kobo sync, there are a few things you can do to help identify the problem:
- enable debug logs on the Kobo itself
- search for
devmodeonon the kobo - go to settings -> device information -> on page 2, developer options
- here you can enable logs for specific settings
- enable debug logs in calibre
- go to the calibre web admin panel
- go to basic configuration
- expand
Logfile configuration - adjust the log level (and location)
- optionally (though very useful) enable the access log
- monitor logs from the Kobo during a sync
- figure out the IP of your Kobo (you can do this from settings -> device information)
- run netcat to view the logs on your local machine:
nc $KOBO_IP 5001
- if you're using a reverse proxy (such as nginx), enable access/error logs
- see nginx documentation for steps on how to do this for your setup
- see reverse proxy setup instructions here
- in particular note that standard nginx proxy header buffers may be too small evidenced by "upstream sent too big header while reading response header from upstream" errors, you should adjust proxy_buffer_size, proxy_buffers and proxy_busy_buffers_size (there are many suggestions online for appropriate values).
Checking Kobo sync content
If you have trouble downloading books, please check the output of the kobo sync by entering the following address in your browser: [server-ip and port]/kobo/[kobo_token]/v1/library/sync You should get some structured text output where you can check the metadata of the books and also the download links generated.
In the Calibre-Web log the output should be something like the following:
[2022-03-24 18:25:57,201] INFO {cps.kobo:140} Kobo library sync request received.
[2022-03-24 18:25:57,201] DEBUG {cps.kobo:141} SyncToken: 0001-01-01 00:00:00,0001-01-01 00:00:00,0001-01-01 00:00:00,0001-01-01 00:00:00,0001-01-01 00:00:00,
[2022-03-24 18:25:57,201] DEBUG {cps.kobo:143} Kobo: Received unproxied request, changed request port to external server port
[2022-03-24 18:25:57,300] DEBUG {cps.kobo:215} Books to Sync: 4
[2022-03-24 18:25:57,492] DEBUG {cps.kobo:280} Remaining books to Sync: 0
It's also a good idea to activate the access log in your Calibre-Web instance to check how far the sync process is getting until the error occurs.
Additional hints
The HTTP headers using Kobo sync is quite large. With some reverse proxies in between, the header can be too large to sync. In this case please increase the allowed maximum header size in your proxy config.
Nginx example:
proxy_busy_buffers_size 1024k;
proxy_buffers 4 512k;
proxy_buffer_size 1024k;
If you are using a reverse proxy you may have to change the api_endpoint link to https:// instead of http://