Deploying Komga

Introduction

Komga is a free and open source media server designed specifically for comics, mangas, BDs (bandes dessinées), magazines, and eBooks. Built with Kotlin and Spring Boot, Komga provides a powerful web interface for organizing, browsing, and reading your digital comic and manga collection from any device with a web browser.

The application automatically scans your library folders, extracts metadata from your files, and organizes everything into a searchable, browsable interface. Komga supports a wide range of formats including CBZ, CBR, PDF, and EPUB, making it compatible with most digital comic and manga collections.

Key features of Komga:

• Multi-Format Support: Read CBZ, CBR, PDF, and EPUB files directly in your browser
• Automatic Metadata: Extracts and displays embedded metadata from your comic files
• OPDS Support: Compatible with any OPDS reader app for mobile reading
• Multi-User System: Create multiple users with different library access permissions
• Reading Progress: Tracks your reading progress across devices
• Web Reader: Built-in reader with page preloading and keyboard navigation
• REST API: Full API access for third-party app integration
• Webtoon Mode: Special reading mode for vertical-scroll comics
• Series Management: Organize comics into series with proper ordering
• Duplicate Detection: Identifies duplicate files in your library

This guide walks through deploying Komga on Klutch.sh using Docker, configuring persistent storage for your comic library, and setting up the application for production use.

Why Deploy Komga on Klutch.sh

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

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Komga without complex orchestration. Push to GitHub, and your media server deploys automatically.

Persistent Storage: Attach persistent volumes for your comic library, database, and configuration. Your collection and reading progress survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your library from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your library size. Start small and scale up as your collection grows.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Komga instance for easy access and sharing.

Always-On Availability: Your comic library remains accessible 24/7 without managing your own hardware.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Komga configuration
• Basic familiarity with Docker and containerization concepts
• Your comic/manga library files ready to upload
• (Optional) A custom domain for your Komga instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Komga on Klutch.sh.

Repository Structure

komga-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM gotson/komga:latest

# Set environment variables for user/group IDs
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}

# Set Java options for memory management
ENV JAVA_OPTS=${JAVA_OPTS:--Xmx1g}

# Create directories for libraries
RUN mkdir -p /comics /config

# Expose the web interface port
EXPOSE 25600

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions
JAVA_OPTS	No	-Xmx1g	Java runtime options, adjust memory as needed
SERVER_PORT	No	25600	Port for the web interface
KOMGA_CONFIGDIR	No	/config	Configuration directory path

Deploying Komga on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Komga deployment configuration"
git remote add origin https://github.com/yourusername/komga-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 “komga” or “comics-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 Komga Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 25600 (Komga’s default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
PUID	1000
PGID	1000
JAVA_OPTS	-Xmx1g (adjust based on library size)

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/config	5 GB	Database and application configuration
/comics	100+ GB	Your comic and manga library files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Komga container
• Provision an HTTPS certificate

Access Komga

Once deployment completes, access your Komga instance at https://your-app-name.klutch.sh. Create your admin account on first access.

Initial Setup and Configuration

First-Time Setup

When you first access Komga:

1. Create your administrator account with a secure password
2. Navigate to Settings to configure your instance
3. Add your library paths under Libraries
4. Start the initial library scan

Adding Libraries

To add your comic collection:

1. Go to Settings > Libraries
2. Click Add Library
3. Enter a name and the path to your comics (e.g., /comics)
4. Configure scanning options
5. Save and wait for the initial scan to complete

Configuring Users

Create accounts for family members or friends:

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

OPDS Configuration

Komga provides OPDS feeds for mobile reading apps:

• OPDS URL: https://your-domain/opds/v1.2/catalog
• Page Streaming OPDS: https://your-domain/opds/v1.2/catalog?page_streaming=true

Compatible apps include:

• Panels (iOS)
• Tachiyomi (Android)
• Chunky (iOS)

Troubleshooting Common Issues

Library Not Scanning

• Verify the mount path matches your library configuration
• Check file permissions (PUID/PGID settings)
• Ensure comic files are in supported formats

Memory Issues

• Increase JAVA_OPTS memory allocation
• For large libraries, use -Xmx2g or higher

Slow Performance

• Allocate more CPU and memory resources
• Enable thumbnail caching
• Consider splitting into multiple libraries

Additional Resources

• Official Komga Website
• Komga Documentation
• Komga GitHub Repository
• Komga Discord Community

Conclusion

Deploying Komga on Klutch.sh gives you a powerful, self-hosted comic and manga library with automatic builds, persistent storage, and secure HTTPS access. The combination of Komga’s feature-rich interface and Klutch.sh’s deployment simplicity means you can focus on reading rather than managing infrastructure.