Back to articles
DevOps & Systems

Guide to Building a Personal Manga Storage and Viewing Station with Komga or Kavita on VPS

Detailed guide to deploying Komga or Kavita on VPS using Docker, Nginx/Caddy, ACME SSL, and troubleshooting 502 Bad Gateway, timeouts, and Redis/PgBouncer memory control. Complete...

DPTCloud Engineering4 min read
Guide to Building a Personal Manga Storage and Viewing Station with Komga or Kavita on VPS

Introduction

In the digital age, building a personal manga storage and viewing station on a VPS has become a popular choice for digital content enthusiasts. Applications like Komga and Kavita offer modern interfaces, support multiple file formats (PDF, CBZ, CBR), and professional library management capabilities. This guide provides a detailed walkthrough of deploying these platforms on a VPS using Docker, with practical solutions for common issues such as 502 Bad Gateway errors, timeouts, ACME SSL certificate renewal, and Redis/PgBouncer memory control.

Requirements and Preparation

Before starting, ensure you have:

  • A Linux-based VPS (Ubuntu 22.04/24.04 or Debian 11/12)
  • DNS records configured (e.g., manga.yourdomain.com)
  • SSH access to the VPS
  • Docker and Docker Compose installed
  • A browser supporting HTTPS

We will use Docker to deploy the applications in isolated, manageable containers. This setup also supports rootless containers for enhanced security.

Deploying Komga or Kavita with Docker

1. Create Configuration Folders

Set up directories for storing configuration and data:

mkdir -p /opt/manga/{komga,kavita}/config
mkdir -p /opt/manga/{komga,kavita}/data

2. Create docker-compose.yml File

Choose one of the two applications below, or create separate files.

For Komga:

version: '3.8'

services:
  komga:
    image: ghcr.io/gotson/komga:latest
    container_name: komga
    restart: unless-stopped
    volumes:
      - /opt/manga/komga/config:/config
      - /opt/manga/komga/data:/data
    ports:
      - "8080:8080"
    environment:
      - KOMGA_DATABASE_URL=jdbc:sqlite:/config/komga.db
      - KOMGA_LOG_LEVEL=INFO
    networks:
      - manga-net

networks:
  manga-net:
    driver: bridge

For Kavita:

version: '3.8'

services:
  kavita:
    image: kavita/kavita:latest
    container_name: kavita
    restart: unless-stopped
    volumes:
      - /opt/manga/kavita/config:/config
      - /opt/manga/kavita/data:/data
    ports:
      - "5000:5000"
    environment:
      - KAVITA_DATABASE_URL=sqlite:///config/kavita.db
      - KAVITA_LOG_LEVEL=INFO
    networks:
      - manga-net

networks:
  manga-net:
    driver: bridge

3. Launch the Application

Run Docker Compose to deploy:

cd /opt/manga/komga
sudo docker-compose up -d

Integrating with Nginx/Caddy to Fix 502 Bad Gateway and Timeouts

1. Configure Nginx

To prevent 502 Bad Gateway errors caused by long timeouts, configure Nginx with appropriate parameters:

server {
    listen 80;
    server_name manga.yourdomain.com;

    location / {
        proxy_pass http://localhost: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;

        # Increase timeout values
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        # Limit file size
        client_max_body_size 100M;
    }
}

2. Configure Caddy

Caddy offers simpler configuration due to its automation features:

manga.yourdomain.com {
    reverse_proxy http://localhost:8080 {
        header_up Host {host}
        header_up X-Real-IP {remote}
        header_up X-Forwarded-For {remote}
        header_up X-Forwarded-Proto {scheme}
        timeout_connect 300s
        timeout_send 300s
        timeout_read 300s
    }
}

Automating ACME SSL Certificate Renewal

1. Install Certbot or Use Caddy ACME

For Nginx, use Certbot:

sudo apt install certbot
sudo certbot certonly --nginx -d manga.yourdomain.com

2. Automate Certificate Renewal

Run the command to test and renew certificates:

sudo certbot renew --dry-run

Ensure a daily cron job runs:

0 0 * * * /usr/bin/certbot renew --quiet

Memory Control for Redis and PgBouncer

1. Redis

Redis can consume significant memory if not managed. Optimize by setting policies:

  • maxmemory: Set maximum memory limit
  • maxmemory-policy: Choose eviction strategy (e.g., allkeys-lru)

Edit the redis.conf file:

maxmemory 512mb
maxmemory-policy allkeys-lru

2. PgBouncer

For Kavita, if using PostgreSQL, PgBouncer helps manage connections. Optimize by:

  • Limiting maximum connections
  • Setting connection idle timeout

Edit the pgbouncer.ini file:

[pgbouncer]
max_client_conn = 100
default_pool_size = 20
server_idle_timeout = 60

Troubleshooting

1. 502 Bad Gateway Error

  • Check if the container is running: docker ps
  • Check logs: docker logs komga
  • Ensure Nginx/Caddy is correctly configured with port and proxy
  • Reduce load by increasing timeout values

2. Long Timeouts

  • Increase proxy_read_timeout in Nginx
  • Reduce the number of simultaneous uploads
  • Run the application on a VPS with better CPU/RAM

3. SSL Renewal Failure

  • Check if DNS records are correctly pointed
  • Run certbot renew --dry-run to test
  • Ensure ports 80 and 443 are not blocked

References

For more information on high-performance VPS solutions, you can read the article Network Infrastructure Optimization: Guide to Configuring Multipath TCP (MPTCP) on Linux for VPS Bandwidth Bonding.

Related infrastructure & engineering guides: NVMe Cloud VPS for Docker, Nginx & Databases

DPTCloud Tier III Infrastructure

Recommended NVMe Cloud VPS Plans to Deploy This Setup

Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.

View 22 VPS Plans
ECO · vn-02

VPS-2E

94.600 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 2 GB
  • SSD: 30 GB NVMe
ECO · vn-02Recommended

VPS-3E

170.500 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 4 GB
  • SSD: 50 GB NVMe
BASIC · vn-01Recommended

VPS-05

457.600 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe

Related Articles

View all
ZaloZalo SupportDiscord0384 753 478