Sync KOReader with Dropbox

17 Sep 2024|2 minute read

I use Calibre-Web-Automated as an excellent OPDS server in order to download e-books to all my devices. I also use KOReader’s progressive sync to keep track of my reading progress. However, the reading statistics are not synchronized across devices, which makes it difficult to accurately track my reading habits.

KOReader can sync these statistics (stored in a SQLite3 file) using WebDAV, FTP, or Dropbox, but my Kindle, when not at home, can’t connect to my WebDAV server, leaving Dropbox the only option as it’s accessible from anywhere.

Setting Up Your Dropbox Account

1. Create a Dropbox Account
   If you don’t already have one, sign up for a Dropbox account.

2. Create a Dropbox App
   Go to the Dropbox Developer Page and create a new app.
   Because this account is dedicated solely to syncing the KOReader statistics, grant the app full access to your Dropbox folders and assign it a unique name with all necessary permissions.

Generating API Credentials

You will need to obtain the following:

• App Key
• App Secret
• Refresh Token (which does not expire)

The App Key and App Secret are available on your app’s dashboard. To generate the Refresh Token, follow these steps:

Obtaining an Authorization Code

1. In your app dashboard, navigate to Settings > OAuth 2. Under Redirect URIs, add the following URL, replacing APPKEYHERE with your actual app key:

   https://www.dropbox.com/oauth2/authorize?client_id=APPKEYHERE&response_type=code&token_access_type=offline
   

2. Open the URL in your browser and follow the prompts to authorize the app.

3. Copy the AUTHORIZATION_CODE that is displayed.

Retrieving the Refresh Token

Using the authorization code, App Key, and App Secret, run the following curl command—replacing AUTHORIZATION_CODE, APP_KEY, and APP_SECRET with your actual values:

curl https://api.dropbox.com/oauth2/token \
-d code=AUTHORIZATION_CODE \
-d grant_type=authorization_code \
-u APP_KEY:APP_SECRET

The response will include your Refresh Token.

Configuring KOReader

Finally, insert the obtained credentials into KOReader. You can do this either via the menu (Menu > Tools > Reading Statistics > Settings > Cloud Sync) or directly by editing the Lua configuration file:

return {
    ["cs_servers"] = {
        [1] = {
            ["address"] = "<app_key>:<app_secret>",
            ["name"] = "<app name>",
            ["password"] = "<refresh token>",
            ["type"] = "dropbox",
            ["url"] = "",
        },
    },
}