1 Release 1 Tag

RSS Feed

• v1.0 e2257b2e49

  Compare

  Introducing ComicOPDS: A Modern OPDS Server for Comic Collections Stable

  FrederikBaerentsen released this 2026-01-13 13:52:56 +01:00 | 0 commits to master since this release

  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

  1. Performance First - Every decision prioritizes speed and efficiency
  2. Metadata Aware - Built to work seamlessly with ComicRack's organization system
  3. Mobile Optimized - Designed primarily for tablet/phone reading via OPDS clients
  4. 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:

  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

  Downloads

  • Source Code (ZIP)
  • Source Code (TAR.GZ)