mirror of
https://github.com/gotson/komga.git
synced 2025-01-08 11:47:47 +08:00
better documentation on fat jar usage
added sample configuration.yml for both Windows and Unix/Linux [ci skip]
This commit is contained in:
Gauthier Roebroeck
parent
b196ce8c67
commit
9f923bf793
96
README.md
96
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
|
||||
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
11
doc/sample-configuration/windows/application.yml
Normal file
11
doc/sample-configuration/windows/application.yml
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user