From 9f923bf79394070455997e63e4d833b448c2fb3f Mon Sep 17 00:00:00 2001 From: Gauthier Roebroeck Date: Mon, 23 Sep 2019 11:52:26 +0800 Subject: [PATCH] better documentation on fat jar usage added sample configuration.yml for both Windows and Unix/Linux [ci skip] --- README.md | 96 ++++++++++++------- doc/docker-compose.yml | 17 ---- .../unix}/application.yml | 2 +- .../windows/application.yml | 11 +++ 4 files changed, 73 insertions(+), 53 deletions(-) delete mode 100644 doc/docker-compose.yml rename doc/{ => sample-configuration/unix}/application.yml (64%) create mode 100644 doc/sample-configuration/windows/application.yml diff --git a/README.md b/README.md index b08f0429..5a901979 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,10 @@ Komga is a free and open source comics/mangas server. Komga just started, and for now it can: -- scan and index a folder containing comic book archives in `cbz` and `cbr` format, as well as `pdf`. Rescan periodically. +- scan and index a root folder 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 an API - serve the complete file via an API +- support for OPDS feed ## Status & vision @@ -27,6 +28,51 @@ Future versions may bring: The long term vision is to offer something similar to Plex, but for comics! +## Installation + +### Docker + +The easiest way to run Komga is via Docker. Please refer to the ([instructions on how to use the image](https://hub.docker.com/r/gotson/komga)). + +### Jar file + +Alternatively you can run it from the fat `jar` file. You can find them in the [releases](https://github.com/gotson/komga/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 for Komga to run properly, read on to the next section to find out more. + +## Configuration + +Komga relies heavily on [Spring Boot's configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html), 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](./doc/sample-configuration/windows/application.yml) and [Unix/Linux](./doc/sample-configuration/unix/application.yml). + +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;DB_CLOSE_DELAY=-1`, where `/config/database.h2` is the actual file inside the docker container. You can customize this part if running without docker. +- `KOMGA_ROOT_FOLDER` / `komga.root-folder`: the root folder of your library, this is what Komga will scan. +- `KOMGA_ROOT_FOLDER_SCAN_CRON` / `komga.root-folder-scan-cron`: a [Spring cron expression](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/support/CronSequenceGenerator.html) for root folder 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_USER_PASSWORD` / `komga.user-password`: the password for the user `user`. Defaults to `user`. +- `KOMGA_ADMIN_PASSWORD` / `komga.admin-password`: the password for the user `admin`. Defaults to `admin`. +- `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. + ## What does it do? Komga will scan your library's root folder for directories containing supported files (at the moment `cbz`, `zip`, `cbr`, `rar` and `pdf`): @@ -37,11 +83,11 @@ Komga will scan your library's root folder for directories containing supported It works with subfolders too, so if you have a structure like this: ``` --Parent -+--SubFolder -| +file1.cbz -| +file2.cbz -+direct1.cbz +Parent/ +├── SubFolder/ +│ ├── file1.cbz +│ └── file2.cbz +└── direct1.cbz ``` Komga will generate: @@ -53,42 +99,22 @@ On rescans, Komga will update Series and Books, add new ones, and remove the one Then it will _parse_ each book, which consist of indexing pages (images in the archive), and generating a thumbnail. +## APIs + +### 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, with one of the 2 built-in users (`admin` or `user`). -## Installation +### OPDS -The easiest way to install Komga is to use Docker ([instructions on how to use the image](https://hub.docker.com/r/gotson/komga)). You can have a look at the sample [`docker-compose.yml`](./doc/docker-compose.yml). +Komga offers a standard OPDS feed, it is available at `/opds/v1.2/catalog`. -Alternatively you can run it from the fat `jar` file. You can find them in the [releases](https://github.com/gotson/komga/releases) section. +The OPDS feed also supports: -You can also build it yourself by using `gradlew bootJar` to generate it. - -## Configuration - -Komga relies heavily on [Spring Boot's configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html), 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 the sample [`application.yml`](./doc/application.yml). - -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;DB_CLOSE_DELAY=-1`, where `/config/database.h2` is the actual file inside the docker container. You can customize this part if running without docker. -- `KOMGA_ROOT_FOLDER` / `komga.root-folder`: the root folder of your library, this is what Komga will scan. -- `KOMGA_ROOT_FOLDER_SCAN_CRON` / `komga.root-folder-scan-cron`: a [Spring cron expression](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/scheduling/support/CronSequenceGenerator.html) for root folder 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_USER_PASSWORD` / `komga.user-password`: the password for the user `user`. Defaults to `user`. -- `KOMGA_ADMIN_PASSWORD` / `komga.admin-password`: the password for the user `admin`. Defaults to `admin`. -- `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. +- OpenSearch functionality, to search by `Serie` +- [OPDS Page Streaming Extension 1.0](https://vaemendis.net/opds-pse/) ## Credits diff --git a/doc/docker-compose.yml b/doc/docker-compose.yml deleted file mode 100644 index 98deb5e1..00000000 --- a/doc/docker-compose.yml +++ /dev/null @@ -1,17 +0,0 @@ ---- -version: '3' -services: - komga: - image: gotson/komga - container_name: komga - volumes: - - ~/opt/appdata/komga:/config - - /mnt/nas/media/Books/:/books - - /etc/timezone:/etc/timezone:ro - ports: - - 8090:8080 - user: "1000:1000" - environment: - - KOMGA_USER_PASSWORD=your-user-password - - KOMGA_ADMIN_PASSWORD=your-admin-password - restart: unless-stopped diff --git a/doc/application.yml b/doc/sample-configuration/unix/application.yml similarity index 64% rename from doc/application.yml rename to doc/sample-configuration/unix/application.yml index 60557633..9d070bbf 100644 --- a/doc/application.yml +++ b/doc/sample-configuration/unix/application.yml @@ -5,6 +5,6 @@ komga: admin-password: admin-password spring: datasource: - url: jdbc:h2:/config/database.h2;DB_CLOSE_DELAY=-1 + url: jdbc:h2:./komga-database.h2;DB_CLOSE_DELAY=-1 #database will be located in the current directory profiles: active: prod \ No newline at end of file diff --git a/doc/sample-configuration/windows/application.yml b/doc/sample-configuration/windows/application.yml new file mode 100644 index 00000000..18d09ccb --- /dev/null +++ b/doc/sample-configuration/windows/application.yml @@ -0,0 +1,11 @@ +komga: + root-folder: D:\\your\\library\\root\\directory + root-folder-scan-cron: "* */15 * * * ?" #periodic scan every 15 minutes + user-password: user-password + admin-password: admin-password +spring: + datasource: + url: jdbc:h2:./komga-database.h2;DB_CLOSE_DELAY=-1 #database will be located in the current directory + # url: jdbc:h2:D:\\komga\komga-database.h2;DB_CLOSE_DELAY=-1 #database absolute path, uncomment if necessary and comment above line + profiles: + active: prod \ No newline at end of file