kavita-uploader

An auxiliary service for Kavita that provides an upload function based on existing user auth.

Motivation

Kavita's author has a strict aversion to adding file upload, citing separation of concerns:

https://github.com/Kareadita/Kavita/discussions/2668#discussion

Regardless, there is an expressed, natural use case of users wanting to upload files when there is no leeching stack feeding the library. My non-technical partner isn't going to bother with arr-like apps or an sftp client... she just wants to upload artifacts to Kavita on an individual basis, and making this work is easier than switching server apps, so here we are.

How it Works

This is a sidecar API/web app that has write access to the same file system backing Kavita's libraries. It uses the UI session token (JWT) given to the user upon UI auth, so it has to be available at the same domain origin as Kavita itself (i.e. front them with a reverse proxy). The uploader uses the JWT and the Kavita API to figure out what libraries the user should have upload access to. It places files in the desired library in an expected format.

Optionally, you can configure it with an API key for an admin user, which enables additional capabilities (initially added to support triggering immediate library scans).

Installation

Install on a machine or pod that has write access to the library file systems and use a web proxy (apache, nginx, etc) to host it behind the same origin as Kavita but under a different slug.

For example, if this were your Kavita: https://kavita.example.com/

You could set up your proxy to redirect another URL slug to the uploader port:

https://kavita.example.com/upload/

Apache example config, assuming Kavita is on port 5000 and the uploader is listening on the same host on port 8080:

    ProxyPreserveHost On

    ProxyPass        "/upload/" "http://127.0.0.1:8080/"
    ProxyPassReverse "/upload/" "http://127.0.0.1:8080/"
    ProxyPass        "/"        "http://127.0.0.1:5000/"
    ProxyPassReverse "/"        "http://127.0.0.1:5000/"

Nginx example config for the same situation:

    location /upload/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:5000/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

...neither of these are complete working examples; there is other confguration necessary to make Kavita fully functional when behind a reverse proxy. See the Kavita wiki page on reverse proxying for full details.

Configuration

The main setting you'll need to set at a minimum:

UPLOADSLUG (match your rproxy config; for the examples, the correct value is "/upload")

...others may be needed as well depending on your setup. Likely:

• UPLOADBUFFERDIR (where files are held after upload and before being moved to a library)
• BINDADDR ([ip]:[port] for the uploader API)
• LIBRARYROOT (if libraries are /data/library/a, /data/library/b, but Kavita sees them as /library/a, /library/b, the correct value is "/data")

All config is done via envvars; see config/config.go.

Usage

Once running at the same origin as Kavita, navigate to [your kavita url]/[upload slug]/.

File Type Support Plan

• epub (yes)
• pdf (soon)
• cb[7rtz] (maybe someday)
• raw images (maybe, probably not)