# Configuration options
TIP
Komga has sensible default values for all configuration keys. You only need to configure it if you want to change the default behaviour.
The application.yml
file does not exist by default, you need to create one if you want to customize the configuration.
Komga relies heavily on Spring Boot's configuration (opens new window), leveraging profiles
and configuration properties
.
The easiest way to configure is either via environment variables (a good fit for docker
and docker-compose
) or by using an application.yml
file located in the configuration directory:
- The Docker image will load any
application.yml
file located in the/config
mounted folder. - The Jar will load any
application.yml
file located in thekomga.config-dir
directory (defaults to~/.komga
, more details).
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
.
You can also specify configuration via the command line, when launching the jar
. Use the application-property
form, and prefix with --
. For example:
java -jar komga.jar --server.servlet.context-path="/komga" --server.port=8443
# Optional configuration
You can use some optional configuration keys:
# KOMGA_CONFIGDIR / komga.config-dir: <directory>
The Komga configuration directory. Will be used to store the logs, database, and any other file Komga needs.
Defaults to ~/.komga
. ~
is your home directory on Unix, and your User profile on Windows.
When overriding this configuration, you need to use ${user.home}
instead of ~
(this is a specific Spring Boot variable).
# SERVER_PORT / server.port: <port>
Port to listen to for the API and web interface.
Defaults to 8080
.
# SERVER_SERVLET_CONTEXT_PATH / server.servlet.context-path: <baseUrl>
Base URL, useful if you need to reverse proxy with a subfolder.
Defaults to /
.
# KOMGA_LIBRARIES_SCAN_CRON / komga.libraries-scan-cron: <cron>
A Spring cron expression (opens new window) for libraries periodic scans.
For example 0 0 * * * ?
will rescan every hour. 0 */15 * * * ?
will rescan every 15 minutes.
To disable the periodic scan, set the value to -
.
Defaults to 0 0 */8 * * ?
(every 8 hours).
# KOMGA_LIBRARIES_SCAN_STARTUP / komga.libraries-scan-startup: <true/false>
A boolean indicating if Komga should scan your libraries at startup.
Defaults to false
.
# KOMGA_LIBRARIES_SCAN_DIRECTORY_EXCLUSIONS / komga.libraries-scan-directory-exclusions: <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 you need to use a comma-separated list.
Defaults to #recycle,@eaDir,@Recycle
.
# KOMGA_REMEMBERME_KEY / komga.remember-me.key: <key>
If set, the remember-me auto-login feature will be activated, and will generate a cookie with encoded login information to perform auto-login. Set <key>
to any random string.
Not set by default, you need to set it to enable this feature.
# KOMGA_REMEMBERME_VALIDITY / komga.remember-me.validity: <duration>
The validity of the generated remember-me cookie. You can specify the timeunit, for example 14d
for 14 days, or 24h
for 24 hours. If no unit is set, seconds will be used.
Defaults to 2 weeks.
# KOMGA_SESSIONTIMEOUT / komga.session-timeout: <duration>
The duration after which an inactive session will expire. You can specify the timeunit, for example 14d
for 14 days, or 24h
for 24 hours. If no unit is set, seconds will be used.
Defaults to 7 days.
# KOMGA_DATABASE_FILE / komga.database.file: <file path>
File path for the SQLite database.
If you want to change the directory, it is advised to change komga.config-dir
instead.
Defaults to:
\${komga.config-dir}/database.sqlite
for Jar./config/database.sqlite
for Docker.
# KOMGA_CORS_ALLOWED_ORIGINS / komga.cors.allowed-origins: <origins>
A list of origins to allow for CORS.
Defaults to empty list.
# KOMGA_DELETE_EMPTY_COLLECTIONS / komga.delete-empty-collections: <true/false>
A boolean indicating if Komga should delete empty collections after a scan.
Defaults to true
.
# KOMGA_DELETE_EMPTY_READ_LISTS / komga.delete-empty-read-lists: <true/false>
A boolean indicating if Komga should delete empty read lists after a scan.
Defaults to true
.
# KOMGA_FILE_HASHING / komga.file-hashing: <true/false>
removed since 0.143.0
This has been moved to Library options.
# KOMGA_OAUTH2_ACCOUNT_CREATION / komga.oauth2-account-creation: <true/false>
A boolean indicating whether Komga should create new users when a login via OAuth2/OIDC succeeds, but there is no existing user with that email.
Such users will be created with a random password, which the user can subsequently change from the Account Settings page later on, for example to be able to connect using OPDS or Tachiyomi.
WARNING
It is recommended to enable this only with OAuth2 providers you control
Defaults to false
.
# KOMGA_OIDC_EMAIL_VERIFICATION / komga.oidc-email-verification: <true/false>
A boolean indicating whether Komga should check whether the email_verified
claim is present and true in the OpenID Connect request.
WARNING
It is recommended to disable this only with OIDC providers that do not verify emails (like Azure AD)
Defaults to true
.
# LOGGING_FILE_NAME / logging.file.name: <logfile name>
Name of the log file.
If you want to change the directory, it is advised to change komga.config-dir
instead.
Defaults to:
\${komga.config-dir}/komga.log
for Jar./config/logs/komga.log
for Docker.
When overriding this configuration, you need to use ${user.home}
instead of ~
(this is a specific Spring Boot variable).
# KOMGA_TASKCONSUMERS / komga.task-consumers: <int>
The initial number of thread that will consume tasks. Must be positive and lower or equal to komga.task-consumers-max
.
Defaults to 1
.
# KOMGA_TASKCONSUMERSMAX / komga.task-consumers-max: <int>
The maximum number of thread that will consume tasks. Must be positive and greater or equal to komga.task-consumers
.
Defaults to 1
.
# Sample Configuration File
Here is a sample application.yml
file in case you need to customize it. Keep only the lines you need.
# Only keep lines that are relevant to you!
# Lines starting with # are comments
# Make sure indentation is correct (2 spaces at every indentation level), yaml is very sensitive!
komga:
libraries-scan-cron: "0 0 */8 * * ?" # periodic scan every 8 hours
libraries-scan-cron: "-" # disable periodic scan
libraries-scan-startup: false # scan libraries at startup
libraries-scan-directory-exclusions: # patterns to exclude directories from the scan
- "#recycle" # synology NAS recycle bin
- "@eaDir" # synology NAS index/metadata folders
- "@Recycle" # QNAP NAS recycle bin
remember-me:
key: changeMe! # required to activate the remember-me auto-login via cookies
validity: 30d # validity of the cookie in seconds, here 30 days
session-timeout: 7d # session timeout, here 7 days
database:
file: ${user.home}/.komga/database.sqlite
cors.allowed-origins:
- http://localhost:8081
- http://localhost:8082
delete-empty-collections: true
delete-empty-read-lists: true
server:
port: 8080
servlet.context-path: /komga
# Database performance
WARNING
Use at your own risk!
Some specific configuration keys are available to tweak the database performance.
komga:
database:
# sets the retry timeout when SQLITE_BUSY error happens
busy-timeout: 30s
# changes the journal mode
# accepted values are: DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF
# most likely to be set to wal if needed, check https://sqlite.org/wal.html for more details
journal-mode: wal
# pool size will determine the number of connections in the pool
# this takes precedence over max-pool-size if set
# defaults to undefined
pool-size: 1
# max-pool-size will determine the maximum number of connections in the pool
# when set, the number of connections is set to the number of available processors capped at max-pool-size
# defaults to 1
max-pool-size: 8
# pragmas accepts a list of key/value pairs where:
# - key is the pragma name (see https://www.sqlite.org/pragma.html)
# - value is the pragma value
pragmas:
# here are some example pragmas
page_size: 1024
synchronous: OFF
# 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 (opens new window) as a reverse proxy, as it supports the automatic generation of Let's Encrypt (opens new window) certificates.
# Reverse proxy
Here are some sample configuration on how to configure reverse proxy for Komga.
# Caddy (v1)
Without a base URL configured in Komga, using a subdomain:
komga.yourdomain.com {
proxy / http://your-komga-server:8080 {
transparent
}
}
With a base URL configured in Komga:
yourdomain.com {
proxy /komga http://your-komga-server:8080 {
transparent
}
}
# Caddy (v2)
Without a base URL configured in Komga, using a subdomain:
komga.yourdomain.com {
reverse_proxy http://your-komga-server:8080
}
With a base URL configured in Komga:
yourdomain.com {
reverse_proxy /komga/* http://your-komga-server:8080
}