Deploying Kavita

Introduction

Kavita is a fast, feature-rich, cross-platform reading server built with a focus on manga, comics, and books. The application provides a beautiful, responsive web interface for browsing your digital library and a powerful reading experience optimized for various content types.

One of Kavita’s standout features is its OPDS server, enabling integration with mobile reading apps like Chunky on iPad or Panels. Combined with reading progress sync across devices, Kavita ensures you can pick up where you left off whether you’re on your desktop, tablet, or phone.

Key highlights of Kavita:

• Multi-Format Support: Read manga, comics (CBZ, CBR, CB7), books (EPUB, PDF), and raw images
• OPDS Server: Connect mobile apps for seamless reading on any device
• Reading Progress Sync: Track your position across multiple devices automatically
• Smart Collections: Organize content with collections, reading lists, and smart filters
• Metadata Management: Automatic metadata parsing and cover generation
• Multi-User Support: Share your library with family and friends with individual accounts
• Responsive Design: Beautiful interface that works on desktop, tablet, and mobile
• Webtoon Reader: Specialized continuous scroll mode for webtoons
• Customizable Reader: Adjust reading direction, page splitting, and more
• API Access: Full API for automation and third-party integrations

This guide walks through deploying Kavita on Klutch.sh using Docker, configuring your digital library, and optimizing the reading experience.

Why Deploy Kavita on Klutch.sh

Deploying Kavita on Klutch.sh provides several advantages for managing your digital library:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kavita without complex configuration. Push to GitHub, and your reading server deploys automatically.

Persistent Storage: Attach persistent volumes for your library files and reading progress. Your collection and bookmarks survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, enabling secure OPDS connections from mobile apps.

Read Anywhere: Access your entire library from any device with a web browser or OPDS-compatible app.

Always-On Availability: Your reading server remains accessible 24/7, ready whenever you want to read.

Prerequisites

Before deploying Kavita on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• Digital content (manga, comics, ebooks) ready to upload

Preparing Your Repository

To deploy Kavita on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

kavita-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM lscr.io/linuxserver/kavita:latest

# Environment variables
ENV PUID=1000
ENV PGID=1000
ENV TZ=Etc/UTC

# Volume mounts:
# /config - Configuration and database
# /data - Your library content (or /manga, /comics, /books)

EXPOSE 5000

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions
TZ	No	Etc/UTC	Timezone setting

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Deploying Kavita on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Kavita deployment configuration"
git remote add origin https://github.com/yourusername/kavita-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kavita” or “reading-library”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kavita Dockerfile.

Configure HTTP Traffic

Kavita serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5000

Set Environment Variables

Variable	Value
TZ	Your timezone (e.g., America/New_York)
PUID	1000
PGID	1000

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/config	2 GB	Configuration, database, and cover cache
/data	50+ GB	Your library content

You can also create separate mounts for different content types:

Mount Path	Purpose
/manga	Manga collection
/comics	Comic books
/books	Ebooks and PDFs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision HTTPS.

Access Kavita

Once deployment completes, access your Kavita instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

First-Time Setup

When you first access Kavita:

1. Create your admin account with a secure password
2. Log in to access the admin dashboard
3. Navigate to Admin > Libraries to add your content folders

Adding Libraries

Configure your content libraries:

1. Click Add Library in the admin settings
2. Select the library type (Manga, Comics, Books)
3. Add folder paths pointing to your mounted volumes
4. Click Scan Library to index your content

Recommended Folder Structure

Organize your content for optimal metadata detection:

/data/
├── Manga/
│   ├── One Piece/
│   │   ├── Volume 001/
│   │   │   ├── 001.jpg
│   │   │   └── ...
│   │   └── Volume 002/
│   └── Naruto/
├── Comics/
│   └── Batman/
│       └── Batman (2016)/
│           ├── Batman 001.cbz
│           └── Batman 002.cbz
└── Books/
    └── Author Name/
        └── Book Title.epub

Configuring OPDS

Enable OPDS for mobile app integration:

1. Go to Admin > Settings > OPDS
2. Enable the OPDS server
3. Note your OPDS URL: https://your-app-name.klutch.sh/api/opds
4. Use this URL in apps like Chunky, Panels, or Moon+ Reader

Reader Customization

Reading Modes

Kavita supports multiple reading modes:

• Single Page: Traditional page-by-page reading
• Double Page: Two-page spread for desktop
• Webtoon: Continuous vertical scroll for webtoons
• Manga Mode: Right-to-left reading direction

Reader Settings

Customize your reading experience:

1. Click the settings icon while reading
2. Adjust background color, page fit, and splitting
3. Enable/disable page animations
4. Configure keyboard shortcuts

Multi-User Setup

Creating Users

Share your library with others:

1. Navigate to Admin > Users
2. Click Add User
3. Set username, email, and temporary password
4. Assign library access and permissions

User Permissions

Control what each user can access:

• Library Access: Limit which libraries users can see
• Download Permission: Allow or restrict file downloads
• Admin Access: Grant administrative privileges

Production Best Practices

Storage Management

• Monitor Disk Usage: Track storage consumption as your library grows
• Cover Cache: The /config folder stores generated covers
• Database Backups: Regularly back up /config/kavita.db

Performance Optimization

• Scan Scheduling: Configure automatic library scans during off-peak hours
• Cover Generation: Allow initial scans to complete before heavy use

Troubleshooting Common Issues

Content Not Appearing

Solutions:

• Verify folder paths match your volume mounts
• Check file permissions (PUID/PGID settings)
• Trigger a manual library scan
• Review naming conventions match Kavita’s expectations

OPDS Connection Issues

Solutions:

• Ensure OPDS is enabled in settings
• Verify you’re using the correct OPDS URL
• Check that your app supports OPDS
• Some apps require authentication in the URL

Slow Performance

Solutions:

• Allow initial library scans to complete
• Ensure adequate CPU and memory allocation
• Consider separating large libraries into multiple folders

Additional Resources

• Kavita Website
• Kavita Wiki
• Kavita GitHub Repository
• LinuxServer Kavita Image
• Klutch.sh Persistent Volumes

Conclusion

Deploying Kavita on Klutch.sh gives you a powerful, self-hosted reading server with automatic builds, persistent storage, and secure HTTPS access. The combination of Kavita’s rich reading features and Klutch.sh’s deployment simplicity means you can focus on enjoying your manga, comics, and books rather than managing infrastructure.

With OPDS support, multi-device sync, and a beautiful responsive interface, Kavita on Klutch.sh provides the foundation for a personal digital library accessible from anywhere.