Kavita on VPS: installation, configuration, and maintenance

To install, configure, and maintain Kavita on a VPS, you will need a virtual server with a minimum of 2 vCPU, 2-4 GB RAM, and a 20 GB NVMe disk. The process itself involves deployment via Docker Compose, setting up a reverse proxy (Nginx or Caddy) to ensure secure HTTPS access, and implementing backup strategies to protect your comic and ebook library.

Kavita is a modern, fast, and feature-rich media server for managing and reading digital comics, manga, and ebooks (EPUB, PDF). Unlike more general media servers, Kavita focuses specifically on text and graphic content, offering an optimized reading interface, convenient library organization, and access from any device via a web browser. Deploying Kavita on a VPS allows you to create a fully controlled, private library accessible only to you and your selected users, without reliance on third-party cloud services.

The ability to self-host Kavita on your own server provides complete control over your data, high performance, and flexibility in configuration. This is an ideal solution for comic and book collectors looking for a reliable platform to organize and read their digital collection, as well as for those who value privacy and independence from proprietary solutions.

What is Kavita and why do you need it on a VPS?

Kavita is positioned as a high-performance, self-hosted server for reading comics, manga, and ebooks. It supports a wide range of formats, including CBZ, CBR, CBT, CB7, EPUB, PDF, as well as images (JPG, PNG, WebP). The main advantages of Kavita include:

• Intuitive Interface: A modern, responsive web interface that works great on desktops, tablets, and smartphones.
• Collection Support: Ability to create collections, series, and add metadata, which significantly simplifies navigation through a large library.
• Multi-user Access: Supports multiple users with individual profiles, reading progress tracking, and settings.
• Progressive Reading: Automatically saves reading position, allowing you to pick up where you left off on any device.
• Image Optimization: Efficient image processing and compression for fast loading, even when reading large comics.
• API and Integrations: Ability to integrate with other services via API, for example, for metadata import.

Hosting Kavita on a VPS offers several key advantages compared to a local installation or using a home server:

• 24/7 Availability: Your server will be accessible from anywhere in the world at any time, with an internet connection.
• High Speed and Stability: VPS providers, such as Valebyte.com, offer high-speed channels and stable power supply, ensuring uninterrupted operation and fast content loading.
• Scalability: As your library grows or the number of users increases, you can easily upgrade your VPS resources (CPU, RAM, disk) without needing to reinstall.
• Security: The VPS is located in a professional data center with physical security, and the logical security level is entirely under your control.
• Isolation: Your Kavita instance runs in an isolated environment, not affecting other services on your VPS and not being affected by neighboring hosting users, as is the case with shared hosting.

If you already use other self-hosted solutions, such as Calibre-web for ebooks or AudioBookshelf for audiobooks, Kavita will be an excellent addition to your media ecosystem.

Kavita Self-Hosted: Full Control Over Your Library

Self-hosting Kavita means you fully own and manage the server where your data is stored. This gives you an unprecedented level of control over privacy, security, and configuration. You are not dependent on third-party decisions, their privacy policies, or potential failures. All your comics and books remain yours alone, and you decide who accesses them and how. For many enthusiasts and collectors, this is a key factor when choosing a platform for their digital library.

System Requirements for Kavita: Which VPS to Choose?

Choosing the right VPS is critical for comfortable Kavita operation. While Kavita is quite lightweight, its performance directly depends on the size of your library and the number of concurrent users. Valebyte.com offers various tariff plans that may be suitable for Kavita.

Minimum and Recommended Requirements for Kavita

Before proceeding with choosing a VPS, let's consider the basic requirements:

• Processor (CPU): Kavita actively uses the CPU when scanning the library, creating thumbnails, and converting formats. For small libraries and 1-2 users, 1-2 vCPU is sufficient. For medium to large collections (thousands of volumes) and several concurrent users, it's better to have 2-4 vCPU.
• Random Access Memory (RAM): Kavita itself consumes relatively little RAM (100 to 300 MB in idle mode), but the operating system, Docker, and other background processes also require memory.
  • Minimum: 2 GB RAM (for a small library up to 1000 volumes, 1-2 users).
  • Recommended: 4 GB RAM (for medium libraries up to 10,000 volumes, 2-5 users).
  • For large libraries/many users: 8 GB RAM or more.
• Disk Space: This is the most important resource, as comics and ebooks can take up a lot of space.
  • System: Approximately 10-20 GB for the OS and Docker.
  • Library: Depends on your content. One comic can take from 50 MB to several GB. Manga is usually lighter. Ebooks take up less space.
    • 1000 comics: 50 GB - 200 GB.
    • 10,000 comics: 500 GB - 2 TB.
  • Disk Type: Be sure to choose a VPS with NVMe SSD. The high read/write speed of NVMe disks is critical for fast library scanning, thumbnail creation, and comfortable reading, especially for large image files.
• Network Channel: 100 Mbps or 1 Gbps. The higher, the faster users will download content.
• Operating System: Ubuntu Server (20.04 LTS or 22.04 LTS) or Debian (11 or 12) are the most common and well-supported distributions for Docker.

VPS Configuration Recommendations Table for Kavita

Below is a table with approximate VPS configurations from Valebyte.com that are suitable for various Kavita usage scenarios. Prices are indicative and may vary.

Usage Scenario	vCPU	RAM (GB)	Disk (NVMe SSD)	Traffic	Approximate Cost (USD/month)
Personal Use (up to 1000 volumes, 1-2 users)	2	2	100 GB	Unlimited	$5 - $10
Small Library (up to 5000 volumes, 2-5 users)	2-4	4	250 GB	Unlimited	$10 - $20
Medium Library (up to 20,000 volumes, 5-10 users)	4	8	500 GB	Unlimited	$20 - $40
Large Library (over 20,000 volumes, 10+ users)	6-8+	16+	1 TB+	Unlimited	$40+

For most users starting with Kavita, a VPS with 2-4 vCPU, 4 GB RAM, and 250 GB NVMe disk will be an optimal choice. This will provide a good balance of performance and cost. Be sure to verify that your VPS uses KVM virtualization technology, as this guarantees full resource isolation and better performance compared to OpenVZ.

Preparing the VPS for Kavita Installation: Docker and Docker Compose

Deploying Kavita via Docker is the most recommended and straightforward method. Docker provides application isolation, simplifies dependency management, and facilitates updates. Before proceeding with Kavita installation, you need to prepare your VPS.

Initial Server Setup

It is assumed that you have a freshly installed VPS with Ubuntu Server 20.04 LTS or 22.04 LTS. Connect to it via SSH.

ssh user@your_vps_ip

Update the package list and installed packages:

sudo apt update
sudo apt upgrade -y

Install necessary utilities if they are not present:

sudo apt install -y curl wget git nano htop

Installing Docker and Docker Compose

Docker Engine and Docker Compose are the foundation for our deployment. If you want to delve deeper into containers, we recommend reading our article "Containers vs VMs vs Bare-metal Hosting".

Installing Docker Engine:

The most reliable way is to use the official Docker installation script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add your user to the docker group to avoid using sudo with every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Verify that Docker is installed correctly:

docker run hello-world

You should see a welcome message from Docker.

Installing Docker Compose:

Docker Compose allows you to define and run multi-container Docker applications. To install the latest stable version:

sudo apt install docker-compose-plugin -y

Check the Docker Compose version (now it's the docker compose command, not docker-compose):

docker compose version

You should see something like Docker Compose version v2.x.x.

How to Install Kavita on a VPS with Docker Compose?

Now that Docker and Docker Compose are installed, we can proceed with deploying Kavita. We will use the official Kavita image and Docker Compose for easy management.

Creating Directory Structure and docker-compose.yml File

First, create a directory for Kavita where all its configuration files and data will be stored:

mkdir -p ~/kavita/config
mkdir -p ~/kavita/library
cd ~/kavita

Here:

• ~/kavita/config: Will store Kavita's configuration, database, and other important files.
• ~/kavita/library: This is the directory where you will upload your comics, manga, and books.

Create a docker-compose.yml file in the ~/kavita directory:

nano docker-compose.yml

Insert the following content:

version: '3.8'
services:
  kavita:
    image: kizaing/kavita:latest
    container_name: kavita
    environment:
      - TZ=Europe/Moscow # Specify your timezone
    volumes:
      - ./config:/kavita/config # Configuration storage
      - ./library:/kavita/library # Your comic and book library
      # - /path/to/your/additional/library:/kavita/additional_library # Optional: additional library paths
    ports:
      - "5000:5000" # Port for accessing Kavita
    restart: unless-stopped
    networks:
      - kavita_network

networks:
  kavita_network:
    driver: bridge

Save and close the file (Ctrl+O, Enter, Ctrl+X).

Explanation of the docker-compose.yml file:

• version: '3.8': Specifies the Docker Compose syntax version.
• image: kizaing/kavita:latest: Uses the official Kavita image. :latest means the latest stable version.
• container_name: kavita: Assigns a name to the container for easy identification.
• environment: - TZ=Europe/Moscow: Sets the timezone inside the container. Replace with your own.
• volumes:: Defines mounted volumes. This is very important as it allows Kavita data to be stored outside the container.
  • ./config:/kavita/config: The local directory ~/kavita/config is mounted to /kavita/config inside the container. Kavita will store its database, cache, and settings here.
  • ./library:/kavita/library: The local directory ~/kavita/library is mounted to /kavita/library inside the container. This is the location for your media files.
  • You can add additional volumes for other content folders if you have multiple sources.
• ports: - "5000:5000": Forwards container port 5000 to host system port 5000. Kavita runs on port 5000 by default.
• restart: unless-stopped: The container will automatically restart if it stops for any reason (e.g., after a VPS reboot), unless you stop it manually.
• networks:: Defines an internal network for Kavita. This is useful if you plan to run other services (e.g., a reverse proxy) in Docker and want them to communicate over the internal network.

Starting Kavita Docker

In the ~/kavita directory, where your docker-compose.yml is located, execute the command to start Kavita:

docker compose up -d

This command will download the Kavita image, create the container, and run it in the background (-d). The process will take some time on the first run, as Docker will download the image.

Check the status of running containers:

docker compose ps

You should see the kavita container with a status of Up.

Now Kavita is accessible at your VPS's IP address on port 5000: http://your_vps_ip:5000. Open this address in your browser to complete Kavita's initial setup (creating an administrator, adding libraries).

Adding Files to the Kavita Library

After successfully installing Kavita, you will need to add your media files. Upload your comics, manga, and books to the ~/kavita/library directory on your VPS. You can use SCP, SFTP (via FileZilla), or rsync for this.

Example upload via SCP:

scp -r /path/to/your/local/comics user@your_vps_ip:~/kavita/library/

After uploading the files, go to the Kavita web interface, navigate to the "Libraries" section, and add a new library, specifying the path /kavita/library (or any other path you mounted into the container).

Setting Up Reverse Proxy (Nginx/Caddy) and HTTPS for Kavita

Direct access to Kavita via IP address and port 5000 is neither secure nor convenient. To ensure secure access via a domain name with encryption (HTTPS), you need to set up a reverse proxy. We will cover two popular options: Nginx and Caddy.

Why do you need a Reverse Proxy and HTTPS?

• Security (HTTPS): Encrypting traffic between your browser and Kavita protects your data from interception. Let's Encrypt provides free SSL/TLS certificates.
• Convenience: Access via a nice domain name (e.g., kavita.yourdomain.com) instead of an IP address and port.
• Centralization: A reverse proxy can serve multiple web applications on a single VPS, directing requests to the correct container based on the domain name.
• Additional Features: Caching, load balancing, basic authentication, and other capabilities.

For this part, you will need a registered domain name and an A-record pointing to your VPS's IP address (e.g., kavita.yourdomain.com -> your_vps_ip).

Option 1: Setting Up Nginx as a Reverse Proxy

Nginx is a powerful and widely used web server that excels as a reverse proxy. Install Nginx if it's not already installed:

sudo apt install nginx -y

Create a new configuration file for Kavita:

sudo nano /etc/nginx/sites-available/kavita.conf

Insert the following content, replacing kavita.yourdomain.com with your domain:

server {
    listen 80;
    listen [::]:80;
    server_name kavita.yourdomain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name kavita.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/kavita.yourdomain.com/fullchain.pem; # Path to your certificate
    ssl_certificate_key /etc/letsencrypt/live/kavita.yourdomain.com/privkey.pem; # Path to your private key

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";
    ssl_prefer_server_ciphers off;
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";
    add_header Referrer-Policy "no-referrer-when-downgrade";
    add_header Content-Security-Policy "frame-ancestors 'self'";

    location / {
        proxy_pass http://localhost:5000; # Or http://kavita:5000 if Nginx is also in the Docker network
        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;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 900s;
        proxy_send_timeout 900s;
        proxy_connect_timeout 900s;
    }
}

Save and close the file.

Obtaining an SSL Certificate with Let's Encrypt (Certbot)

Install Certbot for Nginx:

sudo apt install certbot python3-certbot-nginx -y

Create a symbolic link to your configuration file:

sudo ln -s /etc/nginx/sites-available/kavita.conf /etc/nginx/sites-enabled/

Check the Nginx configuration for errors:

sudo nginx -t

If there are no errors, reload Nginx:

sudo systemctl reload nginx

Now obtain the SSL certificate:

sudo certbot --nginx -d kavita.yourdomain.com

Follow Certbot's instructions. It will automatically update your Nginx config to use HTTPS. After this, Certbot will add a cron job for automatic certificate renewal.

If you are using other services, such as Navidrome or Gitea on the same VPS, you can use the same Nginx to proxy them.

Option 2: Setting Up Caddy as a Reverse Proxy

Caddy is a modern web server with automatic HTTPS (via Let's Encrypt), which makes it very easy to configure. To install Caddy, follow the official instructions, for example:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Create a Caddyfile:

sudo nano /etc/caddy/Caddyfile

Remove existing content and insert the following, replacing kavita.yourdomain.com with your domain:

kavita.yourdomain.com {
    reverse_proxy localhost:5000 # Or kavita:5000 if Caddy is also in the Docker network
    # Additional headers for security (optional, but recommended)
    header {
        X-Frame-Options SAMEORIGIN
        X-XSS-Protection "1; mode=block"
        X-Content-Type-Options nosniff
        Referrer-Policy "no-referrer-when-downgrade"
        Content-Security-Policy "frame-ancestors 'self'"
    }
}

Save and close the file.

Check the Caddy configuration:

sudo caddy validate --config /etc/caddy/Caddyfile

Restart Caddy:

sudo systemctl restart caddy

Caddy will automatically obtain and renew SSL certificates for your domain. Now Kavita will be accessible at https://kavita.yourdomain.com.

Maintaining Kavita on the Server: Backups and Updates

Regular maintenance of Kavita on the server is key to its stable and secure operation. This includes creating backups and timely updates.

Kavita Backups

Backups are your insurance against data loss. In the case of Kavita, the most important items are the database and configuration files, as well as the comic library itself.

Since you are using Docker Compose and mounted volumes, the backup process is relatively simple:

1. Stop the Kavita container (optional, but recommended for database consistency):

   cd ~/kavita
   docker compose stop

2. Create an archive of the data:

   Archive the config and library directories.

   tar -czvf kavita_backup_$(date +%Y%m%d_%H%M%S).tar.gz ~/kavita/config ~/kavita/library

   This command will create an archive with a name containing the current date and time.

3. Move the backup to a safe location:

   Do not store backups on the same VPS as the original data. Move them to remote storage (S3-compatible storage, FTP server, Google Drive/Dropbox via rclone, or to a local computer).

   scp kavita_backup_*.tar.gz user@your_backup_server:/path/to/backups/

4. Start the Kavita container:

   cd ~/kavita
   docker compose start

Automating Backups with Cron:

You can automate this process by creating a bash script and adding it to the Cron scheduler. Create a file named backup_kavita.sh:

nano ~/backup_kavita.sh

Script content (replace /path/to/remote/backup/ with your path):

#!/bin/bash

BACKUP_DIR="/root/kavita_backups" # Temporary directory for backups on VPS
KAVITA_DATA_DIR="/root/kavita"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/kavita_backup_${TIMESTAMP}.tar.gz"
REMOTE_BACKUP_TARGET="user@your_backup_server:/path/to/remote/backup/" # Example: [email protected]:/mnt/backups/kavita/

mkdir -p "$BACKUP_DIR"

echo "Stopping Kavita container..."
docker compose -f "${KAVITA_DATA_DIR}/docker-compose.yml" stop

echo "Creating backup of Kavita data..."
tar -czvf "$BACKUP_FILE" -C "${KAVITA_DATA_DIR}" config library

echo "Starting Kavita container..."
docker compose -f "${KAVITA_DATA_DIR}/docker-compose.yml" start

echo "Transferring backup to remote storage..."
scp "$BACKUP_FILE" "$REMOTE_BACKUP_TARGET"

echo "Cleaning up local backup file..."
rm "$BACKUP_FILE"

echo "Kavita backup completed."

Make the script executable:

chmod +x ~/backup_kavita.sh

Add a Cron job (for example, for daily backup at 3 AM):

crontab -e

Add the following line to the end of the file:

0 3 * * * /root/backup_kavita.sh > /dev/null 2>&1

Be sure to configure passwordless SSH access (SSH keys) for the user running the script so that scp can work automatically.

Updating Kavita and Docker

Regular updates are important for new features, bug fixes, and security patches.

Updating Kavita

To update Kavita to the latest version, simply run a few commands:

cd ~/kavita
docker compose pull # Downloads the latest Kavita image
docker compose up -d # Recreates the container with the new image, preserving data

Kavita handles database migration itself when necessary, so the update process usually goes smoothly.

Updating Docker and OS

It is also important to keep Docker Engine, Docker Compose, and your VPS's operating system up to date:

sudo apt update
sudo apt upgrade -y

After an OS kernel update, a VPS reboot may be required:

sudo reboot

After rebooting, make sure all Docker containers (including Kavita) have started automatically (thanks to restart: unless-stopped).

Optimal VPS Configuration for Kavita Under Real Load

Choosing the optimal VPS configuration for Kavita depends on many factors: the size of your library, the number of active users, access frequency, and other services that may be running on the same VPS. For monitoring server resources and making scaling decisions, we recommend using tools like Netdata.

Factors Affecting Load and VPS Choice

1. Library Size:
   • Small (up to 1000 volumes): 2 vCPU, 2-4 GB RAM, 100-250 GB NVMe.
   • Medium (1000-10000 volumes): 4 vCPU, 4-8 GB RAM, 250-500 GB NVMe.
   • Large (over 10000 volumes): 6-8+ vCPU, 8-16+ GB RAM, 1 TB+ NVMe.

   The more files, the more time is required for initial scanning and thumbnail creation, which stresses the CPU and disk subsystem. After indexing, CPU load decreases, but disk requests remain high during reading.

2. Number of Concurrent Users:
   • 1-2 users: Minimum requirements are usually sufficient.
   • 3-5 users: 4 vCPU and 4 GB RAM are desirable for comfortable operation.
   • More than 5 users: 6-8 vCPU and 8+ GB RAM. Each active user, especially reading heavy comics, can increase CPU and I/O consumption.
3. Content Type:
   • Comics/Manga (CBR/CBZ): Usually contain many high-resolution images, requiring more disk I/O and network bandwidth.
   • Ebooks (EPUB/PDF): Take up less space and are less resource-intensive when reading.
4. Disk Subsystem Speed:

   NVMe SSD is critically important. The difference between NVMe and regular SSDs or HDDs will be noticeable when scanning the library, loading comic pages, and working with the database.

5. Network Bandwidth:

   If you have many users or frequently upload large files, ensure your VPS has a high-speed network channel (1 Gbps).

Scaling Recommendations

Start with a configuration that meets your current needs and be prepared to scale it as you grow. Most VPS providers, including Valebyte.com, allow you to easily increase your server's resources (CPU, RAM, disk) without reinstalling the OS.

1. Resource Monitoring: Use htop, iotop, docker stats, or Netdata to track CPU, RAM, and disk I/O consumption. If the CPU is consistently loaded at 80-100%, or I/O wait is high, it's a signal to upgrade.
2. Library Optimization: Ensure your files are optimally compressed. Some users re-convert comics to WebP or other more efficient formats to save space and improve performance.
3. Caching: A reverse proxy (Nginx/Caddy) can be configured to cache static content, which will reduce the load on Kavita.
4. Dedicated Server: For very large libraries (tens of thousands of volumes) and a large number of users (20+), it might be worth considering a transition to a dedicated server. This will give you maximum performance and control.

Remember that investing in a more powerful VPS usually pays off through a more comfortable user experience and saved time waiting for content to load.

Conclusion

Installing, configuring, and maintaining Kavita on a VPS via Docker Compose is an effective way to create a powerful and private media server for your comic and ebook collection. The right choice of VPS configuration with NVMe disks, secure access through a reverse proxy with HTTPS, and regular backups will ensure stable, fast, and secure operation of your service. Start with a basic Valebyte.com plan with 2-4 vCPU and 4 GB RAM, and scale resources as your digital library and user base grow.