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...
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_timeoutin 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-runto test - Ensure ports 80 and 443 are not blocked
References
- Komga Documentation
- Kavita Documentation
- Docker Compose Documentation
- Nginx Proxy Module
- Caddy Documentation
- Certbot Documentation
- Redis Documentation
- PgBouncer Documentation
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
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.
VPS-3E
10% VAT included
- CPU: 2 vCPU
- RAM: 4 GB
- SSD: 50 GB NVMe
