Self-host Komga on a managed VPS: your comics and manga on your own server

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.

Simon Vasconcelos Lee By Published on 22 November 202614-minute read

All guides

In short

  1. The MIT license lets you use, modify and redistribute Komga freely, at work or anywhere else, as long as you keep its copyright notice.
  2. Storage is sized on your collection, kept in /data; the database, index and logs live in /config, on a local disk.
  3. Install it with Docker Compose: the gotson/komga image, port 25600 published locally behind an HTTPS reverse proxy, and a user who owns both folders.
  4. The first account created becomes the administrator: create it through an SSH tunnel before you open the server to the public.
  5. Stop Komga, copy the /config folder off the server, keep a copy of your books, and update with docker compose pull.

What Komga does

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.

What the MIT license allows

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.

Memory, CPU and storage: sizing the server

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.

Java memory

The CPU

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”.

Storage for your books

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:

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.

Installing with Docker Compose

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:

Terminal
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:

compose.yaml
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
Terminal
docker compose up -d
docker logs -f komga

Without Docker: the jar file

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:

Terminal
java -version
java -jar komga-1.30.1.jar

The first account and users

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.

Terminal, on your computer
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:

RoleWhat it allows
AdministratorManage libraries, users and collections, edit metadata, run scans, analysis and metadata refreshes
Page StreamingRead page by page, in the webreader for example
File DownloadDownload a book’s file
Kobo SyncSync a Kobo eReader, together with File Download
KOReader SyncSync 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.

Resetting a password from the command line

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:

compose.yaml, under the komga service
    command: --newpassword=YourNewPassword --reset=admin@example.org
Terminal
docker compose up -d

The --list-users command, used the same way, prints the list of accounts in the logs.

Configuration: variables or application.yml

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.

VariablePropertyDefaultWhat it does
SERVER_PORTserver.port25600The port for the API and the web interface
SERVER_SERVLET_CONTEXTPATHserver.servlet.context-path/The base URL, to serve Komga from a subfolder
SPRING_SESSION_TIMEOUTspring.session.timeout7 daysHow long an inactive session lasts, for example 14d or 24h
KOMGA_CORS_ALLOWEDORIGINSkomga.cors.allowed-originsNoneThe origins allowed for CORS
LOGGING_LEVEL_ORG_GOTSON_KOMGAlogging.level.org.gotson.komgaNot setDEBUG 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:

compose.yaml, in environment
      - 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.

HTTPS and the reverse proxy

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:

With Caddy

On a subdomain, with no base URL in Komga, Caddy sets these headers itself:

Caddyfile
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:

Caddyfile
example.com {
    reverse_proxy /komga/* 127.0.0.1:25600
}

With Nginx

The Nginx example in the documentation also forwards WebSocket connections. Add this map block to the http section of /etc/nginx/nginx.conf:

nginx.conf, in http
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:

Nginx block
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;
    }
}
Terminal
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.

Libraries, scans and imports

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.

  1. Put your files on the server, in one subfolder of ~/komga/data per library, over SFTP or with rsync.
  2. In the interface, click + next to “Libraries”.
  3. Name the library, pick its root folder with “Browse”, for example /data/manga, then click “Add”.
Terminal, on your computer
rsync -av manga/ user@komga.example.com:komga/data/manga/

The trash

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.

Importing books

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.

Read anywhere: OPDS, Kobo and KOReader

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.

OPDS

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:

OPDS addresses
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.

Kobo Sync

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.

  1. Give the account the Kobo Sync and File Download roles.
  2. Generate an API key on your account page, “Account Settings”, and write it down: it is shown only once. Use one key per eReader.
  3. Connect the Kobo to your computer and open the .kobo/Kobo/Kobo eReader.conf file, with hidden files shown.
  4. In the [OneStoreServices] group, replace the api_endpoint line with your server address followed by your key.
Kobo eReader.conf
api_endpoint=https://komga.example.com/kobo/YOUR_API_KEY

KOReader Sync

KOReader reads Komga over OPDS, and syncs its read progress through the Komga sync server:

  1. Give the account the KOReader Sync role, and turn on file hashing for KOReader in the library options.
  2. Generate an API key on your account page.
  3. In KOReader, with a book open, go to “Progress sync”, then “Custom sync server”, and enter https://komga.example.com/koreader.
  4. In “Register / Login”, enter the API key as the username, and any value as the password, which Komga does not use.
  5. Under “Document matching method”, choose “Binary”.

Backups

Everything Komga knows about your books lives in /config; your books themselves stay in /data. Here is what /config contains with the default configuration:

ItemWhat it holds
database.sqliteThe main database: libraries, series, books, metadata, users, read progress, collections, read lists and generated thumbnails
tasks.sqlitePending background tasks
sessions.sqliteLogin 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.ymlYour configuration, if you created one

The SQLite databases are copied with Komga stopped, for a consistent copy. From the compose.yaml folder:

Terminal, in ~/komga
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.

Updates

With Docker Compose, the documentation gives these commands, from the compose.yaml folder. The /config folder, mounted from the server, keeps your settings:

Terminal
docker compose pull
docker compose up -d
docker image prune

Who does what on a managed VPS

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.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
KomgaProactive monitoring: errors, slowdowns, memory and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Libraries and readersThe server that carries them, monitored and backed upLibraries, accounts, roles and API keys
BackupsEvery night, encrypted and kept off the machine; restores includedKomga’s own copies, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe 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.

Komga, on a server run for you

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.

Explore Managed VPS

Frequently asked questions

Is Komga free for a business?

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.

How much memory does Komga need?

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.

How do I install Komga with Docker Compose?

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.

How do I create the Komga admin account?

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.

Which OPDS address do I give my reading app?

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.

How do I sync a Kobo eReader with Komga?

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.

How do I back up Komga?

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.

Does a managed VPS cover Komga?

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.

Contact us