komga/README.md

Komga

Komga is a free and open source comics/mangas server.

Features

Features include:

• scan and index libraries (local folders) containing sub-folders with comic book archives in cbz and cbr format, as well as pdf. Rescan periodically.
• serve the individual pages of those books via API. It can convert pages to different image format on the fly.
• serve the complete file via API
• provide OPDS feed
• web interface

Installation

Docker

The easiest way to run Komga is via Docker. Please refer to the (instructions on how to use the image).

Jar file

Alternatively you can run it from the fat jar file. You can find them in the releases section.

In order to run Komga, use the following command:

java -jar komga-x.y.z.jar

Note that you need to have a valid application.yml configuration file (or environment variables) for Komga to run properly, read on to the next section to find out more.

Configuration

Komga relies heavily on Spring Boot's configuration, leveraging profiles and configuration properties.

The easiest way to configure is either via environment variables (a good fit for docker-compose) or by using an application.yml file located in the same folder as the jar file.

You can check sample application.yml files for Windows and Unix/Linux.

Each configuration key can have a different format depending if it's from the environment variable, or from the application.yml file. In the following section I will provide both format in the form ENVIRONMENT_VARIABLE / application-property.

Mandatory configuration

In order to make Komga run, you need to specify some mandatory configuration keys (unless you use Docker, in which case defaults are setup):

• SPRING_PROFILES_ACTIVE / spring.profiles.active: prod - this will enable the database management and upgrades for new versions.
• SPRING_DATASOURCE_URL / spring.datasource.url: the path of the database file. For Docker I use jdbc:h2:/config/database.h2, where /config/database.h2 is the actual file inside the docker container. You can customize this part if running without docker.
• KOMGA_LIBRARIES_SCAN_CRON / komga.libraries-scan-cron: a Spring cron expression for libraries periodic rescans. 0 0 * * * ? will rescan every hour. 0 */15 * * * ? will rescan every 15 minutes.

Optional configuration

You can also use some optional configuration keys:

• KOMGA_THREADS_PARSE / komga.threads.parse: the number of worker threads used for book parsing. Defaults to 2. You can experiment to get better performance.
• KOMGA_LIBRARIES_SCAN_DIRECTORY_EXCLUSIONS / komga.libraries-scan-directory-exclusions: a list of patterns to exclude directories from the scan. If the full path contains any of the patterns, the directory will be ignored. If using the environment variable form use a comma-separated list.

What does it do?

Komga will scan your libraries for directories containing supported files (at the moment cbz, zip, cbr, rar and pdf):

• each folder containing comic books will be made as a Series
• each comic book file inside a Series will be made as a Book

It works with sub-folders too, so if you have a structure like this:

Comics/
├── Private Eye/
│   ├── Volume 1.cbz
│   └── Volume 2.cbz
└── One Shot.cbz

Komga will generate:

• a Series called Comics, containing a Book called One Shot
• a Series called Private Eye, containing two Books called Volume 1 and Volume 2

On rescans, Komga will update Series and Books, add new ones, and remove the ones for which files don't exist anymore.

Then it will parse each book, which consist of indexing pages (images in the archive), and generating a thumbnail.

Security

User accounts

At startup, if no user account exists in database, Komga will generate an initial administrator account with a random password, and will output the login and password in the logs:

2019-10-15 17:15:31.483  INFO 18808 --- [  restartedMain] o.g.k.i.scheduler.InitialUserController  : Initial user created. Login: admin@example.org, Password: 2Qf8l85xOB8o

❗ It is strongly advised to create your own account, and delete the generated account!

HTTPS

If you want to open your Komga server outside your local network, it is strongly advised to secure it with https (especially due to the use of http basic authentication).

Spring Boot supports https out of the box, but you will have to configure it, and https is most useful only with valid certificates (not self-signed), which most people don't readily have available.

I recommend using Caddy as a reverse proxy, as it supports the automatic generation of Let's Encrypt certificates.

Clients

Tachiyomi

Komga has an official extension for Tachiyomi, available from within Tachiyomi's extension menu. The extension is configurable, you need to specify the server address, username, and password.

OPDS readers

Komga should work with any OPDS reader, unfortunately most readers badly implement the OPDS protocol 😞.

Here is a list of reader applications I have tested:

OS	App name	Status	OpenSearch support	Page streaming support
Android	FBReader: Favorite Book Reader	❌ Can't download CBR/CBZ, only PDF. PDF only supported in Premium version.	No	No
Android	Moon+ reader	❌ Cannot access CBR/CBZ, get an error 401	No	No
Android	Librera	❌ Doesn't open CBR/CBZ	No	No
Android	PocketBook	❌ Doesn't show CBR/CBZ	No	No
iOS	KyBook 3	✔️	Yes	No
iOS	Chunky Comic Reader	⚠️ Cannot download CBR/CBZ, but can stream pages	No	Yes

Feel free to report your findings with other readers (by sending a PR)!

Web interface

The web interface is available on port 8080.

Features:

• add and remove libraries (for administrators only)
• server settings (for administrators only)
  • users management
• account settings
  • change password

Screenshots:

Home page	Users management

APIs

Default port for APIs is 8080.

Native API

Komga offers a REST API, which you can browse using Swagger. It's available at /swagger-ui.html. The API offers file download and page streaming.

In order to access the API, you will need to authenticate using Basic Authentication.

OPDS

Komga offers a standard OPDS feed, it is available at /opds/v1.2/catalog.

The OPDS feed also supports:

• OpenSearch functionality, to search by Series
• OPDS Page Streaming Extension 1.0

Credits

The Komga icon is based on an icon made by Freepik from www.flaticon.com