Anime-Sanctuary

Kavita

Your scanned comics and ebooks sit in folders, with no bookmark and no cover. Let's install Kavita, a self-hosted reader that shelves them like a library and remembers where you stopped.

Course
Tutorial 24 of 35
Time
35 min to read
Tested with
Commands: tested on Debian 13 (Kavita 0.9.1)
What you will be able to do
  • Write a Compose file for Kavita with its two folders.
  • Arrange and name your files so Kavita understands them.
  • Create the admin account, a library, then accounts for the family.
  • Back up your setup and update Kavita.

Before you start: Docker and Docker Compose.

Contents
  1. What Kavita does
  2. Arrange your files
  3. Write the Compose file
  4. First start
  5. Create the admin account
  6. Add a library
  7. Read in the browser
  8. Accounts for the family
  9. Open it without exposing its port
  10. Back up and update
  11. If it fails
  12. What's next
  13. Sources

How do you install Kavita with Docker Compose on Debian? You need a Compose file of about a dozen lines, two folders and, above all, well-organized files. Plan on thirty-five minutes. You end up with a reader for comics and ebooks in your browser, one that remembers the page where you stopped.

What Kavita does

Kavita is a reader that lives on your server. It shows your scanned comics and ebooks like the shelves of a public library. Each series has its cover, each volume its number, and each reader keeps their own bookmark. Everything opens in a browser, on a computer, a tablet or a phone. Your files never leave your server.

Kavita mostly reads page archives, such as .cbz files. An archive is a file that contains other files. Here it is a plain zip where each image is a page. Kavita also reads ebooks and PDFs. To find its way around, it needs your files arranged in a precise way, so that is where we start.

1Arrange your files

Kavita expects one folder per series, with the volumes inside. A file dropped straight at the root of the library is ignored, and two folders for the same series split it in two. To find the volume, Kavita reads the number in the file name. An example series, Aventures de Pixel, looks like this:

  • One folder per series: Aventures de Pixel.
  • One file per volume, with the title then the number: Aventures de Pixel T01.cbz, Aventures de Pixel T02.cbz. The v01 form, which the documentation recommends, works too.

Now let's create Kavita's two folders: one for its settings, one for the files to read.

On the server
mkdir -p ~/kavita/config ~/kavita/bd
cd ~/kavita

Drop your files from your computer with rsync, covered in Your first backup with rsync. The BD folder in the command is yours, with one folder per series.

On your computer
rsync -av BD/ alice@203.0.113.10:kavita/bd/

The files are in place. Next, describe the container that will read them.

2Write the Compose file

One service is enough: Kavita keeps its database in its config folder. The Compose file builds on what you learned in Docker and Docker Compose. It links your two folders to the container and keeps the port for the server only.

The user line sets the Linux account that Kavita runs as. It will be yours rather than root, the administrator account, which limits the damage if Kavita has a security hole. That account is written as two numbers. id -u gives your user number, and id -g gives your group number. If alice was the first account created, both show 1000.

On the server
id -u
id -g

If you see something else, replace "1000:1000" with your two numbers. In the next command, cat copies the text between <<'EOF' and the EOF line into docker-compose.yml.

On the server
cat > docker-compose.yml <<'EOF'
services:
  kavita:
    image: jvmilazz0/kavita:0.9.1
    restart: unless-stopped
    user: "1000:1000"
    ports:
      - "127.0.0.1:5000:5000"
    volumes:
      - ./config:/kavita/config
      - ./bd:/books:ro
    environment:
      TZ: Europe/Paris
EOF

Every line has a reason:

  • jvmilazz0/kavita:0.9.1: the official image, pinned to one version. Nothing changes unless you decide it.
  • 127.0.0.1:5000:5000: port 5000 is open to the server only. That is deliberate, and we come back to it below.
  • ./config:/kavita/config: the settings, the accounts and the covers. The path on the right must stay exactly like this.
  • user: "1000:1000": the account Kavita uses to read and write its folders, the one you just checked.
  • ./bd:/books:ro: your files to read, read-only (ro). Kavita can open them but never change them.
  • TZ: your time zone, so that dates are right. Change it if you don't live in Paris.

The file is ready. Let's switch Kavita on.

3First start

The first command downloads the image, then starts the container. The -d option of up -d keeps it running in the background, so your terminal stays free. Kavita then prepares its files for almost a minute.

On the server
sudo docker compose up -d

After a minute, ask whether it is ready to answer.

On the server
curl -s http://127.0.0.1:5000/api/health
Expected output
Ok

If you get a connection error, wait ten seconds and try again. Kavita is running, but nobody has an account yet. Time to create yours.

4Create the admin account

On first launch, Kavita offers to create an account, and that first account becomes the administrator. Until it exists, anyone who reaches the port can create it: first come, first served. That is why the port is kept for the server, and why you go through a tunnel.

An SSH tunnel links port 5000 on your computer to port 5000 on the server, through the SSH connection. You saw one in Nextcloud. Keep this window open during the setup.

On your computer
ssh -L 5000:127.0.0.1:5000 alice@203.0.113.10

Open http://localhost:5000 in your browser. Kavita asks for a user name, a password and an email address. Use alice, a long password from your password manager, and any address you like. alice@exemple.fr will do, because Kavita sends nothing until you set up email sending.

You land on an empty home page. Your server has an administrator, and it's you. Now you have to show it your files.

5Add a library

A library is a folder you hand over to Kavita, with a type that says how to read its content. In the server settings, open the libraries tab and add one.

  • Name: whatever you like, for example "BD".
  • Type: "Comic" for Western comics, "Manga" for manga, "Book" for ebooks. This choice changes how file names are read.
  • Folder: /books. That is the path inside the container, the one on the right in the Compose file.

Confirm, and Kavita scans the folder. Allow a few seconds for a handful of files, and longer for a big collection.

Each volume shows up with its cover in the Aventures de Pixel series. So Kavita reads your files and their numbers. Let's open one.

6Read in the browser

Click a series, then a volume, and the reader opens full screen. A menu sets the display, for example the zoom. Kavita notes the page where you stop and offers it again on your next visit.

On your computer, everything already works through the tunnel. A phone, however, doesn't know your localhost. It needs the public HTTPS address from step 8. First, let's see how to open the door to the family.

Phone apps

Kavita also works with third-party apps, listed in its wiki. They need the same public HTTPS address.

7Accounts for the family

Each person has their own account, with their own progress and bookmarks. You choose what each one can see. In the server settings, the users tab lets you invite someone:

  • Email address: the person's own.
  • Roles: the right to log in is enough to read. Keep "Admin" for yourself.
  • Libraries: tick the ones they may see.

Until email sending is set up, Kavita can't send the invitation. It gives you a link to pass on yourself. That link lets someone create the account, so send it to the right person only, in a private message.

Everyone can then log in, and you no longer have to share your password. These accounts only matter if the others can reach the server. Step 8 puts it on the Internet, with a solid front door.

8Open it without exposing its port

Opening port 5000 as it is would send your family's passwords in clear text over the Internet. You need a solid front door: a Reverse proxy. It receives visitors over HTTPS, with the certificate from HTTPS with Let's Encrypt, then passes their request on to 127.0.0.1:5000.

The setup is the one from the dedicated article, with the address 127.0.0.1:5000 and a domain name, for example kavita.exemple.fr, covered in Domain name and DNS. Kavita also keeps a connection open with the browser at all times. So Apache needs two modules, features you switch on separately. proxy_wstunnel lets that connection through, and rewrite recognizes it and routes it. Here is the complete VirtualHost, with the three lines specific to Kavita.

On the server
sudo tee /etc/apache2/sites-available/kavita.exemple.fr.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName kavita.exemple.fr
    ProxyPreserveHost On
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:5000/$1 [P,L]
    ProxyPass / http://127.0.0.1:5000/
    ProxyPassReverse / http://127.0.0.1:5000/
    RequestHeader set X-Forwarded-Proto expr=%{REQUEST_SCHEME}
</VirtualHost>
EOF

Next, enable the two modules, then the site and its certificate as in the reverse proxy article. a2enmod switches on a module, and reload makes Apache reread its configuration without stopping.

On the server
sudo a2enmod proxy_wstunnel rewrite
sudo systemctl reload apache2

You won't use the tunnel any more: the address becomes https://kavita.exemple.fr. The whole Internet can now reach the login page. Keep your passwords long, and create accounts only for people you trust. One thing is left: keeping a copy of what you built.

9Back up and update

What matters is the config folder: accounts, libraries, everyone's progress and the covers. Your files are backed up separately, as in Your first backup with rsync. For a consistent copy, you stop Kavita for a few seconds, archive config with tar, which packs the folder into one compressed file, then restart.

On the server
cd ~/kavita
sudo docker compose stop
tar czf kavita-config.tar.gz config
chmod 600 kavita-config.tar.gz
sudo docker compose start

The archive holds your accounts and the invitation links. chmod 600 keeps it for you alone, so don't leave it readable by everyone. It is small, a few dozen KB for a test library. Copy it somewhere else: a backup that stays on the server won't save you from a breakdown.

Restore the settings

Stop Kavita, set the current settings aside, extract the archive in ~/kavita, which recreates config, then restart.

On the server
cd ~/kavita
sudo docker compose stop
mv config config.ancien
tar xzf kavita-config.tar.gz
sudo docker compose up -d

To update, back up first, then download the new image and recreate the container.

On the server
sudo docker compose pull
sudo docker compose up -d

This update changes nothing as long as the number 0.9.1 stays in the file. To move to a newer version, change that number, then run the two commands again.

If it fails

Three situations come back often:

  • A file doesn't show up. It sits at the root of the library. Put each series in its own folder. In our test, a file left at the root was not counted, and the same file inside a folder became a series.
  • A series has a strange name. Kavita uses the folder name. Our folder Scan Final became the series "scan final". Rename the folder, then rescan the library.
  • Kavita sees nothing although everything is in place. Your account may not be able to read the files. Test with sudo docker compose exec kavita ls /books. Give the files to Kavita's account, the one on the user line: sudo chown -R 1000:1000 ~/kavita/bd, with your two numbers if they aren't 1000. Don't make them readable by every account on the server.

What's next

Your movies and your books each have their own reader, with accounts for the family. Every service now has a password, and more will come. The next article, Vaultwarden, installs a password manager on your server, so you stop memorizing them one by one.