Komga

Komga is a self‑hosted media server designed to ingest, organize, and serve comic books, manga, BD, magazines, and e‑books. From a developer’s perspective it functions as a full‑stack Java application exposing a comprehensive REST API, OPDS feeds, and WebSocket endpoints for real‑time updates. It parses a wide range of archive formats (CBZ, CBR, PDF, EPUB), extracts embedded metadata, and normalizes it into a relational schema that supports advanced queries such as “next unread in series” or “books matching label X”. The core of Komga is the library engine that watches file system changes, deduplicates content (both files and pages), and exposes the catalog through its API.

Architecture

• Language & Runtime: Java 17+ running on the JVM. The backend is built with Spring Boot, leveraging its dependency injection, security, and data access modules.
• Persistence: PostgreSQL is the default relational database; it stores metadata, user accounts, permissions, collections, and read‑status. The schema is auto‑generated via JPA/Hibernate, allowing migrations with Flyway.
• File Storage: The application stores media in the local file system or any network‑mounted volume. It maintains a library abstraction that maps directories to logical collections.
• Web Layer: A modern React/TypeScript front‑end communicates with the API via JSON over HTTPS. The UI is built as a single‑page application, but Komga also serves static assets for mobile browsers and OPDS clients.
• API: RESTful endpoints cover CRUD operations on libraries, series, books, users, and collections. Webhooks are available for external services to react to events such as “book added” or “read‑status changed”.
• Containerization: A Docker image (gotson/komga) is available, containing the JAR and a bundled PostgreSQL option. The image supports environment variables for configuration and can be orchestrated with Docker Compose or Kubernetes.

Core Capabilities

Deployment & Infrastructure

Komga is designed for low‑overhead, single‑node deployments but scales horizontally with a shared PostgreSQL database and stateless API servers. Docker images simplify provisioning; the container can be run with a single docker run command or integrated into CI/CD pipelines. For production, best practice is to:

1. Persist the database separately (PostgreSQL container or managed service).
2. Mount a dedicated volume for media to avoid data loss on image updates.
3. Use reverse proxy (NGINX, Traefik) to provide TLS termination and path routing.
4. Optionally deploy multiple API replicas behind a load balancer; the database handles concurrency.

Integration & Extensibility

• Plugins: Komga’s modular architecture allows adding custom Spring beans that hook into lifecycle events (e.g., after import). The plugin API is documented in DEVELOPING.md.
• Webhooks: External services can register callbacks for events such as book_added or series_updated. Payloads are JSON and can be filtered by library or label.
• OAuth2/OpenID: Supports external authentication providers; developers can integrate with Keycloak, Auth0, or custom SSO solutions.
• CLI & SDK: A minimal Java client library wraps the REST API, making it easy to build companion tools or dashboards.

Developer Experience

• Documentation: The official website hosts API docs (Swagger/OpenAPI), user guides, and a developer handbook. Code comments are concise but thorough.
• Community: Active Discord channel, GitHub discussions, and a translation platform provide rapid feedback loops.
• Testing: The repository includes unit tests (JUnit) and integration tests that run against an embedded H2 database; CI ensures code quality.
• License: AGPL‑3.0, encouraging contributions while protecting the core from proprietary forks.

Use Cases

1. Personal Library Server – Host a private collection of comics and e‑books accessible from home devices.
2. Small Publisher Backend – Use Komga’s API to expose a catalog to partner readers and integrate with custom front‑ends.
3. Research & Archiving – Store large volumes of digitized books, leveraging duplicate detection and metadata extraction for cataloging.
4. IoT/Embedded – Deploy on a Raspberry Pi to serve a local network of e‑readers via OPDS or Webreader.

Advantages Over Alternatives