When you self-host Komga on a managed VPS, you read your comics, manga and ebooks from a machine of your own, which our teams keep up to date and monitor day and night. Komga is a free software media server under the MIT license. This guide follows its official documentation: the memory and storage to plan for, installing with Docker Compose, the first account, configuration, HTTPS, libraries, reading over OPDS, Kobo and KOReader, backups and updates.
By Simon Vasconcelos Lee
Published on 22 November 202614-minute read
/data; the database, index and logs live in /config, on a local disk.gotson/komga image, port 25600 published locally behind an HTTPS reverse proxy, and a user who owns both folders./config folder off the server, keep a copy of your books, and update with docker compose pull.Komga is a media server for your comics, manga, BDs, magazines and ebooks. You point it at the folders that hold your files, it organizes them into libraries, series and books, then serves them to a browser or a reading app. It runs anywhere Java or Docker runs.
Komga is released under the MIT license, in the name of Gauthier Roebroeck. It grants, free of charge, the right to use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software. You can therefore run it for yourself, your family, your association or your business, with no license to buy.
The only condition is to keep the copyright notice and the license text in all copies or substantial portions of the software. The text provides the software “as is”, without warranty.
The documentation sets no minimum configuration. What it does give is what matters when sizing the server: the memory of the Java virtual machine, the tasks that use the CPU, and above all the space your files take.
OutOfMemoryException errors in the logs. The limit is then raised with the JAVA_TOOL_OPTIONS variable, shown further down.The CPU works mostly during library scans and analysis. For each library, the documentation warns that computing file hashes, page hashes and KOReader hashes, like analyzing page dimensions, can consume lots of resources on a large library. The number of threads dedicated to background tasks is set in “Server Settings”.
This is the largest item, and you measure it on your side: the size of your collection, plus room for the books you plan to add. Komga reads your files where they are and does not copy them. A few points from the documentation change the calculation:
/data folder for books and imports: the documentation asks you to put your libraries and your import folder there, so that imports create hard links instead of copies. Outside the same filesystem, every import takes the space of a copy./config folder holds the main database, with the thumbnails generated for each book, the tasks database, the sessions database, the search index and the logs, which the default configuration keeps for 7 days and caps at 1 GB. It grows with the size of your libraries./config: the SQLite databases must never sit on a network share such as CIFS or NFS. Komga checks this on startup and stops if it is not the case.On a managed VPS, tell us about your collection, its size, how fast it grows and how many readers you have, and we will recommend the right size.
The documentation publishes the gotson/komga image on Docker Hub and on ghcr.io, for amd64, arm64 and arm processors. On a server with Docker installed, create a folder for Komga with its two subfolders, and note your user ID:
mkdir -p ~/komga/config ~/komga/data/import
cd ~/komga
id
Put this compose.yaml in it, taken from the documentation example. Replace 1000:1000 with the uid and gid values shown by id, and TZ with your time zone:
services:
komga:
image: gotson/komga:1.x
container_name: komga
volumes:
- type: bind
source: ./config
target: /config
- type: bind
source: ./data
target: /data
ports:
- "127.0.0.1:25600:25600"
user: "1000:1000"
environment:
- TZ=Europe/London
restart: unless-stopped
docker compose up -d
docker logs -f komga
127.0.0.1: this is the main departure from the documentation example, which publishes it on every address. The documentation strongly advises HTTPS as soon as Komga is opened outside your local network, because it uses HTTP basic authentication. The interface is then reached only through the reverse proxy.user. The documentation asks that the mounted folders be owned by that same user: permission issues then disappear./config holds the Komga database and configuration, on a local disk./data holds your books and your import folder. Each library will have its own subfolder there.1.x tag follows the latest published version 1; 1.30.1 pins a version. The documentation describes latest as the latest commit.version line of the documentation example is left out: Docker Compose now treats it as obsolete and ignores it.The other route in the documentation for a Linux server is the jar file of each release, published on GitHub. It needs Java 17 or later, and keeps its configuration in ~/.komga:
java -version
java -jar komga-1.30.1.jar
On first access, Komga asks you to create an account: an email address and a password. That first account receives every role, administration included, and “claims” the server. Until it exists, this form answers anyone who reaches the page: create it before you open the server to the public, through an SSH tunnel. The server’s port 25600 then appears on your computer, at http://localhost:25600. Add -p and the SSH port shown in your customer area.
ssh -L 25600:127.0.0.1:25600 user@komga.example.com
Further accounts are created by the administrator, under “Server Settings”, “Users”, with the + button. Each account gets the roles it needs:
| Role | What it allows |
|---|---|
| Administrator | Manage libraries, users and collections, edit metadata, run scans, analysis and metadata refreshes |
| Page Streaming | Read page by page, in the webreader for example |
| File Download | Download a book’s file |
| Kobo Sync | Sync a Kobo eReader, together with File Download |
| KOReader Sync | Sync read progress with KOReader |
Deleting a user erases all of their read progress, with no way back: a copy of /config made just before keeps you in control.
The documentation adds the command to compose.yaml, under the komga service; Komga applies the change, then starts as usual. Restart the service, then remove the line and restart it once more:
command: --newpassword=YourNewPassword --reset=admin@example.org
docker compose up -d
The --list-users command, used the same way, prints the list of accounts in the logs.
Komga has default values for every setting: configuration only changes its behavior. It is done with environment variables, the easiest route with Docker Compose, or with an application.yml file you create in the /config folder, where the Docker image loads it. To turn a property name into a variable name, replace dots with underscores, remove dashes and convert to uppercase.
| Variable | Property | Default | What it does |
|---|---|---|---|
SERVER_PORT | server.port | 25600 | The port for the API and the web interface |
SERVER_SERVLET_CONTEXTPATH | server.servlet.context-path | / | The base URL, to serve Komga from a subfolder |
SPRING_SESSION_TIMEOUT | spring.session.timeout | 7 days | How long an inactive session lasts, for example 14d or 24h |
KOMGA_CORS_ALLOWEDORIGINS | komga.cors.allowed-origins | None | The origins allowed for CORS |
LOGGING_LEVEL_ORG_GOTSON_KOMGA | logging.level.org.gotson.komga | Not set | DEBUG for detailed logs |
The port and the base URL can also be set under “Server Settings”, and that setting then takes precedence over the configuration. For Java memory, add the JAVA_TOOL_OPTIONS variable to the environment section. The documentation example sets a maximum of 4 GB:
- JAVA_TOOL_OPTIONS=-Xmx4g
The sample application.yml in the documentation starts with the database path. With Docker, keep it on /config/database.sqlite, its default value: anywhere else, the database would be created inside the container and lost when it is recreated. Keep only the lines of the sample that you need.
The documentation recommends putting a reverse proxy in front of Komga that obtains a valid certificate, and suggests Caddy, which generates its own Let’s Encrypt certificates. The proxy must set three headers, so that Komga knows the public address and the protocol of each request:
X-Forwarded-For, set or augmented;X-Forwarded-Proto;X-Forwarded-Host.On a subdomain, with no base URL in Komga, Caddy sets these headers itself:
komga.example.com {
reverse_proxy 127.0.0.1:25600
}
In a subfolder, first set the Komga base URL to /komga, under “Server Settings” or with SERVER_SERVLET_CONTEXTPATH, then:
example.com {
reverse_proxy /komga/* 127.0.0.1:25600
}
The Nginx example in the documentation also forwards WebSocket connections. Add this map block to the http section of /etc/nginx/nginx.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
This site block uses the settings from the documentation example, on port 80 so that Certbot can set up HTTPS. The X-Forwarded-Host line is added, since the documentation’s list of headers asks for it:
server {
listen 80;
listen [::]:80;
server_name komga.example.com;
client_max_body_size 20000m;
location / {
proxy_pass http://127.0.0.1:25600;
proxy_http_version 1.1;
proxy_redirect off;
proxy_buffering off;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}
}
sudo nginx -t
sudo certbot --nginx
The full example in the documentation shows the final version: port 80 redirected to HTTPS, and the block on 443 with its certificate paths.
A library is a group of books, kept under a root folder. Komga creates a series for each subfolder, at any depth, and a book for each file, placed in the series of its parent folder. Metadata from EPUB files and from the ComicInfo.xml files inside archives takes precedence over folder and file names.
~/komga/data per library, over SFTP or with rsync./data/manga, then click “Add”.rsync -av manga/ user@komga.example.com:komga/data/manga/
/data/manga and /data/comics live side by side; /data and /data/manga cannot.#recycle.A book whose file disappears moves to the trash, marked “Unavailable”, instead of being deleted: its metadata, read progress and lists come back if the file reappears in its place. You can therefore rename and move your files without losing anything. The trash is emptied by hand, or after every scan if you turn that option on, which then removes items right away.
The “Import”, “Books” screen files into your series books that sit in another folder of the server, /data/import for example. For each file, you choose the destination series, the number and the name; a number already in use offers to upgrade the existing book, with both shown side by side. Komga moves the files, or hard links them when the filesystem allows it, and copies them otherwise.
Changing a library’s root folder to a path unrelated to the old one erases its series, books and read progress. The FAQ describes how to move it: file hashing on, automatic trash emptying off, then a scan before the move.
The webreader opens in the browser, at the server’s address. For an app or an eReader, Komga offers three doors, all to be served over HTTPS.
Komga works with any OPDS app, version 1 or 2. Give the app one of these addresses, then the email address and password of your Komga account:
https://komga.example.com/opds/v2/catalog
https://komga.example.com/opds/v1.2/catalog
The version 1.2 catalog adds search by series, through OpenSearch, and page-by-page reading without downloading, through the OPDS PSE extension. The documentation keeps a list of tested apps, on Android, iOS and elsewhere, with what each one supports.
Your Kobo eReader syncs with Komga instead of the official Kobo servers. EPUB books from all libraries arrive with their metadata and cover, converted to KEPUB on the fly by Kepubify, which ships in the Docker image. Read progress syncs both ways.
.kobo/Kobo/Kobo eReader.conf file, with hidden files shown.[OneStoreServices] group, replace the api_endpoint line with your server address followed by your key.api_endpoint=https://komga.example.com/kobo/YOUR_API_KEY
api_endpoint address, 443 for an HTTPS address.KOReader reads Komga over OPDS, and syncs its read progress through the Komga sync server:
https://komga.example.com/koreader.Everything Komga knows about your books lives in /config; your books themselves stay in /data. Here is what /config contains with the default configuration:
| Item | What it holds |
|---|---|
database.sqlite | The main database: libraries, series, books, metadata, users, read progress, collections, read lists and generated thumbnails |
tasks.sqlite | Pending background tasks |
sessions.sqlite | Login sessions, stored in the database by default since version 1.30.0 |
lucene/ | The search index |
fonts/ | Fonts |
logs/ | The logs, including komga.log |
application.yml | Your configuration, if you created one |
The SQLite databases are copied with Komga stopped, for a consistent copy. From the compose.yaml folder:
docker compose stop
tar -czf komga-config-$(date +%F).tar.gz config
docker compose start
Send this archive off the server, as often as you add and read books. Also keep a copy of your books, with the covers you keep next to the files: it is the heaviest volume, but it changes little, and rsync only sends what is new. Kept on the server’s disk, these archives are also part of its nightly backups.
To restore, stop Komga, replace the config folder with the one from the archive, check that it is still owned by the user in compose.yaml, then start it again.
With Docker Compose, the documentation gives these commands, from the compose.yaml folder. The /config folder, mounted from the server, keeps your settings:
docker compose pull
docker compose up -d
docker image prune
/config just before each update.jar file, stop Komga, then start it with the jar of the new version.Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Komga remains your software, with its settings and your books.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| Komga | Proactive monitoring: errors, slowdowns, memory and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Libraries and readers | The server that carries them, monitored and backed up | Libraries, accounts, roles and API keys |
| Backups | Every night, encrypted and kept off the machine; restores included | Komga’s own copies, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Komga instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is complimentary.
Yes. Komga is under the MIT license: you can use, modify and redistribute it at work with no license to buy, as long as you keep its copyright notice. What remains is the cost of the server that runs it.
The documentation sets no minimum. By default, Java limits Komga’s memory, usually around 1 GB. If the logs show OutOfMemoryException errors, raise the limit with JAVA_TOOL_OPTIONS, for example -Xmx4g for 4 GB.
Create a compose.yaml with the gotson/komga image, port 25600 published on 127.0.0.1, a config folder mounted on /config, a data folder mounted on /data, and a user who owns both, then run docker compose up -d. Next, put an HTTPS reverse proxy in front of port 25600.
On first access, Komga asks for an email address and a password: that first account receives every role. Create it through an SSH tunnel before you open the server to the public, then create the other accounts under Server Settings, Users.
Your server address followed by /opds/v2/catalog for OPDS 2, or by /opds/v1.2/catalog for OPDS 1.2, with the email address and password of your Komga account.
Give the account the Kobo Sync and File Download roles, generate an API key under Account Settings, then replace the api_endpoint line of the Kobo eReader.conf file with https://your-server/kobo/your-key. Only EPUB books are synced.
Stop Komga, archive the config folder, start it again, and send the archive off the server. Also keep a copy of your books. Make a copy just before each update.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your website
Tell us about your project in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.