Introducing ComicOPDS: A Modern OPDS Server for Comic Collections

Frederik Baerentsen included in Projects Self-Hosting

2025-09-10 778 words 4 minutes

The Problem with Comic Servers

As a long-time comic collector with lots of physical and digital comics, I’ve struggled to find a server solution that actually works well at scale. Most comic servers either:

Ignore or poorly handle ComicRack’s excellent metadata system
Have clunky interfaces that feel stuck in 2010
Require complex setups with multiple services
Don’t properly support modern OPDS features

After years of frustration, I decided to build something better.

Introducing ComicOPDS

ComicOPDS is a lightweight OPDS 1.2 server written in Python, specifically designed for CBZ comics with ComicRack metadata. It’s built on modern technologies (FastAPI + SQLite + FTS5) and optimized from the ground up for large collections.

Key Design Philosophy

Performance First - Every decision prioritizes speed and efficiency
Metadata Aware - Built to work seamlessly with ComicRack’s organization system
Mobile Optimized - Designed primarily for tablet/phone reading via OPDS clients
Simple Deployment - Docker Compose and you’re done

Features That Matter

🔍 Intelligent Search

Full-text search across all metadata fields using SQLite FTS5. Search by series, writer, publisher, year, characters, or any combination. Results are fast even with massive libraries.

📊 Modern Dashboard

A clean, responsive dashboard built with Bootstrap and Chart.js that provides:

Library statistics and trends
Publisher distribution charts
Publication timeline visualization
Index and thumbnail management
Error monitoring and logs

🧠 Smart Lists

Create saved search filters that appear as virtual folders in your OPDS feed. Perfect for:

“Latest issues per series”
“Marvel Comics from 2020-2024”
“Batman family titles”
Custom reading lists

⚡ Optimized Performance

Smart indexing: Only processes changed files
Thumbnail caching: Covers extracted once, served fast
Streaming support: OPDS PSE 1.1 for individual page access
Large library support: Stress tested with 10k+ files

📱 Mobile First

Designed primarily for reading on tablets and phones through OPDS clients like:

Panels for iOS (my primary target)
Chunky Comic Reader (iPad)
Any OPDS-compatible reader

The ComicRack Connection

I’ve been using ComicRack for years to organize my comic collection. It’s hands-down the best tool for comic metadata management, and I even wrote a comprehensive guide on optimal comic organization.

ComicOPDS is built to work seamlessly with ComicRack’s ComicInfo.xml metadata format, utilizing fields like:

Series, Number, Volume, Title
Writer, Penciller, Inker, Colorist
Publisher, Imprint, Genre, Tags
Characters, Teams, Locations
Publication dates and ComicVine integration

If you’re already using ComicRack, ComicOPDS will feel like a natural extension of your workflow.

Technical Details

Architecture

Backend: FastAPI (Python) for fast API performance
Database: SQLite with FTS5 for full-text search
Frontend: Bootstrap + Chart.js for responsive UI
Deployment: Docker + Docker Compose for easy setup

Performance Optimizations

Warm indexing: Persistent metadata cache with smart updates
Lazy thumbnail generation: Covers created on-demand, cached forever
Efficient pagination: Handles large result sets gracefully
File watching: Optional real-time library updates

Security & Administration

HTTP Basic Auth (optional)
Admin endpoints for management tasks
Health checks for monitoring
Comprehensive error logging

Getting Started

The easiest way to try ComicOPDS is with Docker Compose:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


services:
  comicopds:
    image: gitea.baerentsen.space/frederikbaerentsen/comicopds:latest
    container_name: comicopds
    restart: unless-stopped
    ports:
      - "8382:8080"
    environment:
      CONTENT_BASE_DIR: /library
      SERVER_BASE: "http://192.168.1.100:8382"
    volumes:
      - "./comics:/library:ro"
      - "./data:/data"

Then access:

OPDS Feed: http://localhost:8382/
Dashboard: http://localhost:8382/dashboard
Smart Lists: http://localhost:8382/search

Real-World Usage

Performance Metrics

Initial indexing: ~10 minutes for 30k comics (one-time)
Incremental updates: <10 seconds for 100 new comics
Search response: <500ms for most query
Dashboard load: <2 seconds even with full stats

Mobile Experience

Using Panels for iOS as my primary reader:

Smooth browsing through folder hierarchies
Instant search with live results
Fast cover loading with caching
Seamless page streaming for reading

Management Overhead

Minimal: Add comics to folder, they appear automatically
Smart Lists update dynamically as new comics match filters
Dashboard provides all necessary monitoring and controls
Error handling is comprehensive with detailed logs

Getting Involved

Whether you’re a comic collector, developer, or both, there are many ways to contribute:

Try it out: Test with your library and provide feedback
Report issues: Help identify bugs and edge cases
Contribute code: PRs welcome for fixes and enhancements
Spread the word: Share with other comic collectors

Conclusion

ComicOPDS represents months of focused development, informed by years of frustration with existing solutions. It’s designed by a comic collector, for comic collectors, with a deep understanding of how people actually organize and read their collections.

If you’re tired of slow, clunky comic servers that don’t respect your carefully curated library, give ComicOPDS a try. I think you’ll find it refreshingly fast and intuitive.

Links:

Repository: https://gitea.baerentsen.space/FrederikBaerentsen/ComicOPDS
ComicRack Guide: https://comicrack.baerentsen.space/
Support: Buy Me a Coffee

Have questions or feedback? Reach out on reddit as /u/public_fred or open an issue on the repository. I’d love to hear about your experience!

Contents