Hospedar Komga em um VPS gerenciado: seus quadrinhos e mangás em seu servidor

Hospedar Komga em um VPS gerenciado é ler seus quadrinhos, seus mangás e seus e-books a partir de uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O Komga é um servidor de mídia livre sob a licença MIT. Este guia segue a documentação oficial dele: a memória e o armazenamento a prever, a instalação com Docker Compose, a primeira conta, a configuração, o HTTPS, as bibliotecas, a leitura por OPDS, Kobo e KOReader, os backups e as atualizações.

Simon Vasconcelos Lee Por Publicado em 22 de novembro de 2026Leitura: 15 minutos

Todos os guias

O essencial

  1. A licença MIT permite usar, modificar e redistribuir o Komga livremente, em uma empresa ou fora dela, desde que você mantenha o aviso de copyright dele.
  2. O armazenamento é dimensionado por sua coleção, guardada em /data; o banco, o índice e os logs ficam em /config, em um disco local.
  3. Instale-o com Docker Compose: a imagem gotson/komga, a porta 25600 publicada localmente atrás de um proxy reverso em HTTPS e um usuário dono das duas pastas.
  4. A primeira conta criada vira a de administrador: crie-a por um túnel SSH antes de abrir o servidor ao público.
  5. Pare o Komga, copie a pasta /config para fora do servidor, guarde uma cópia de seus livros e atualize com docker compose pull.

O que o Komga faz

O Komga é um servidor de mídia para seus quadrinhos, mangás, quadrinhos franco-belgas, revistas e e-books. Você indica as pastas onde estão seus arquivos, ele os organiza em bibliotecas, séries e livros e depois os serve a um navegador ou a um aplicativo de leitura. Ele roda em qualquer lugar onde Java ou Docker rodem.

O que a licença MIT permite

O Komga é publicado sob a licença MIT, em nome de Gauthier Roebroeck. Ela concede gratuitamente o direito de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e vender cópias do software. Você pode, portanto, rodá-lo para você, sua família, sua associação ou sua empresa, sem licença a comprar.

A única condição é manter o aviso de copyright e o texto da licença em todas as cópias ou partes substanciais do software. O texto fornece o software “no estado em que se encontra”, sem garantia.

Memória, CPU e armazenamento: dimensionar o servidor

A documentação não fixa nenhuma configuração mínima. Ela traz, em compensação, o que conta para dimensionar o servidor: a memória da máquina virtual Java, as tarefas que exigem a CPU e, sobretudo, o espaço ocupado por seus arquivos.

A memória do Java

A CPU

A CPU trabalha sobretudo durante as varreduras e as análises das bibliotecas. Para cada uma, a documentação avisa que o cálculo dos hashes de arquivos, dos hashes de páginas e dos hashes para o KOReader, assim como a análise das dimensões das páginas, pode consumir muitos recursos em uma biblioteca grande. O número de threads dedicadas às tarefas em segundo plano é definido em “Server Settings”.

O armazenamento de seus livros

É o item mais pesado, e ele é medido de seu lado: o tamanho de sua coleção, mais o espaço para os livros que você pretende acrescentar. O Komga lê seus arquivos onde eles estão e não os copia. Alguns pontos da documentação mudam a conta:

Em um VPS gerenciado, conte-nos como é sua coleção, o tamanho dela, o ritmo de crescimento e o número de leitores, e recomendamos o tamanho certo.

A instalação com Docker Compose

A documentação publica a imagem gotson/komga no Docker Hub e no ghcr.io, para processadores amd64, arm64 e arm. Em um servidor com o Docker instalado, crie uma pasta para o Komga com as duas subpastas dela e anote seu ID de usuário:

Terminal
mkdir -p ~/komga/config ~/komga/data/import
cd ~/komga
id

Coloque nela este compose.yaml, extraído do exemplo da documentação. Substitua 1000:1000 pelos valores uid e gid exibidos por id, e TZ por seu fuso horário:

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

Sem Docker: o arquivo jar

O outro caminho da documentação para um servidor Linux é o arquivo jar de cada versão, publicado no GitHub. Ele exige Java 17 ou mais recente e guarda sua configuração em ~/.komga:

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

A primeira conta e os usuários

No primeiro acesso, o Komga pede para criar uma conta: um endereço de e-mail e uma senha. Essa primeira conta recebe todas as funções, administração incluída, e “reivindica” o servidor. Enquanto ela não existir, esse formulário responde a qualquer pessoa que chegue à página: crie-a antes de abrir o servidor ao público, por um túnel SSH. A porta 25600 do servidor aparece então em seu computador, em http://localhost:25600. Acrescente -p e a porta SSH indicada em sua área de cliente.

Terminal, em seu computador
ssh -L 25600:127.0.0.1:25600 user@komga.example.com

As contas seguintes são criadas pelo administrador, em “Server Settings”, “Users”, com o botão +. Cada conta recebe as funções de que precisa:

FunçãoO que ela permite
AdministratorGerenciar as bibliotecas, os usuários e as coleções, editar os metadados, iniciar as varreduras, as análises e as atualizações de metadados
Page StreamingLer página por página, no leitor web, por exemplo
File DownloadBaixar o arquivo de um livro
Kobo SyncSincronizar um leitor Kobo, junto com File Download
KOReader SyncSincronizar o progresso de leitura com o KOReader

Excluir um usuário apaga todo o progresso de leitura dele, sem volta: uma cópia de /config feita logo antes deixa você no controle.

Redefinir uma senha pela linha de comando

A documentação acrescenta o comando ao compose.yaml, no serviço komga; o Komga aplica a mudança e depois inicia normalmente. Reinicie o serviço, depois retire a linha e reinicie-o mais uma vez:

compose.yaml, no serviço komga
    command: --newpassword=YourNewPassword --reset=admin@example.org
Terminal
docker compose up -d

O comando --list-users, usado da mesma forma, exibe nos logs a lista das contas.

A configuração: variáveis ou application.yml

O Komga tem valores padrão para cada configuração: configurá-lo serve apenas para mudar o comportamento dele. Isso é feito com variáveis de ambiente, o caminho mais simples com Docker Compose, ou com um arquivo application.yml a criar na pasta /config, onde a imagem Docker o carrega. Para passar do nome de uma propriedade ao de uma variável, substitua os pontos por sublinhados, retire os hifens e passe para maiúsculas.

VariávelPropriedadePadrãoO que ela faz
SERVER_PORTserver.port25600A porta da API e da interface web
SERVER_SERVLET_CONTEXTPATHserver.servlet.context-path/A URL base, para servir o Komga em uma subpasta
SPRING_SESSION_TIMEOUTspring.session.timeout7 diasA duração de uma sessão inativa, por exemplo 14d ou 24h
KOMGA_CORS_ALLOWEDORIGINSkomga.cors.allowed-originsNenhumaAs origens permitidas para CORS
LOGGING_LEVEL_ORG_GOTSON_KOMGAlogging.level.org.gotson.komgaNão definidoDEBUG para logs detalhados

A porta e a URL base também podem ser definidas em “Server Settings”, e essa configuração prevalece então sobre a configuração geral. Para a memória do Java, acrescente a variável JAVA_TOOL_OPTIONS à seção environment. O exemplo da documentação fixa um máximo de 4 GB:

compose.yaml, dentro de environment
      - JAVA_TOOL_OPTIONS=-Xmx4g

O exemplo de application.yml da documentação começa pelo caminho do banco. Com o Docker, mantenha-o em /config/database.sqlite, o valor padrão: em qualquer outro lugar, o banco seria criado dentro do contêiner e perdido quando ele fosse recriado. Mantenha do exemplo apenas as linhas de que você precisa.

O HTTPS e o proxy reverso

A documentação recomenda colocar na frente do Komga um proxy reverso que obtenha um certificado válido, e sugere o Caddy, que gera sozinho os certificados Let’s Encrypt dele. O proxy deve definir três cabeçalhos, para que o Komga conheça o endereço público e o protocolo de cada requisição:

Com o Caddy

Em um subdomínio, sem URL base no Komga, o Caddy define esses cabeçalhos sozinho:

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

Em uma subpasta, defina primeiro a URL base do Komga como /komga, em “Server Settings” ou com SERVER_SERVLET_CONTEXTPATH, e depois:

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

Com o Nginx

O exemplo de Nginx da documentação também repassa as conexões WebSocket. Acrescente este bloco map à seção http de /etc/nginx/nginx.conf:

nginx.conf, dentro de http
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Este bloco de site retoma as configurações do exemplo da documentação, na porta 80 para deixar o Certbot instalar o HTTPS. A linha X-Forwarded-Host foi acrescentada, já que a lista de cabeçalhos da documentação a pede:

Bloco do Nginx
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

O exemplo completo da documentação mostra a versão final: a porta 80 redirecionada para HTTPS e o bloco na 443 com os caminhos dos certificados.

As bibliotecas, as varreduras e as importações

Uma biblioteca é um grupo de livros, guardado sob uma pasta raiz. O Komga cria uma série para cada subpasta, em qualquer profundidade, e um livro para cada arquivo, colocado na série da pasta pai dele. Os metadados dos arquivos EPUB e dos arquivos ComicInfo.xml contidos nos arquivos compactados prevalecem sobre os nomes de pastas e de arquivos.

  1. Coloque seus arquivos no servidor, em uma subpasta de ~/komga/data por biblioteca, por SFTP ou com rsync.
  2. Na interface, clique em + ao lado de “Libraries”.
  3. Dê um nome à biblioteca, escolha a pasta raiz dela com “Browse”, por exemplo /data/manga, e clique em “Add”.
Terminal, em seu computador
rsync -av manga/ user@komga.example.com:komga/data/manga/

A lixeira

Um livro cujo arquivo desaparece vai para a lixeira, marcado como “Unavailable”, em vez de ser excluído: os metadados, o progresso de leitura e as listas dele voltam se o arquivo reaparecer no lugar. Você pode, portanto, renomear e mover seus arquivos sem perder nada. A lixeira é esvaziada manualmente, ou depois de cada varredura se você ativar essa opção, que então exclui os itens na hora.

A importação de livros

A tela “Import”, “Books” coloca em suas séries livros que estão em outra pasta do servidor, /data/import, por exemplo. Para cada arquivo, você escolhe a série de destino, o número e o nome; um número já usado propõe substituir o livro existente, mostrando os dois lado a lado. O Komga move os arquivos, ou cria hard links quando o sistema de arquivos permite, e caso contrário os copia.

Mudar a pasta raiz de uma biblioteca para um caminho sem relação com o anterior apaga as séries, os livros e o progresso de leitura dela. As perguntas frequentes descrevem como movê-la: hashes de arquivos ativados, esvaziamento automático da lixeira desativado e, em seguida, uma varredura antes da mudança.

Ler em qualquer lugar: OPDS, Kobo e KOReader

O leitor web abre no navegador, no endereço do servidor. Para um aplicativo ou um leitor digital, o Komga oferece três portas, todas a servir em HTTPS.

OPDS

O Komga funciona com qualquer aplicativo OPDS, versão 1 ou 2. Informe ao aplicativo um destes endereços, e depois o endereço de e-mail e a senha de sua conta Komga:

Endereços OPDS
https://komga.example.com/opds/v2/catalog
https://komga.example.com/opds/v1.2/catalog

O catálogo na versão 1.2 acrescenta a busca por série, via OpenSearch, e a leitura página por página sem download, via a extensão OPDS PSE. A documentação mantém uma lista de aplicativos testados, no Android, no iOS e em outros sistemas, com o que cada um suporta.

A sincronização com Kobo

Seu leitor Kobo se sincroniza com o Komga no lugar dos servidores oficiais da Kobo. Os livros EPUB de todas as bibliotecas chegam com os metadados e a capa, convertidos para KEPUB na hora pelo Kepubify, incluído na imagem Docker. O progresso de leitura se sincroniza nos dois sentidos.

  1. Dê à conta as funções Kobo Sync e File Download.
  2. Gere uma chave de API na página de sua conta, “Account Settings”, e anote-a: ela só aparece uma vez. Use uma chave por leitor.
  3. Conecte o Kobo a seu computador e abra o arquivo .kobo/Kobo/Kobo eReader.conf, com os arquivos ocultos visíveis.
  4. No grupo [OneStoreServices], substitua a linha api_endpoint pelo endereço de seu servidor seguido de sua chave.
Kobo eReader.conf
api_endpoint=https://komga.example.com/kobo/YOUR_API_KEY

A sincronização com KOReader

O KOReader lê o Komga por OPDS e sincroniza o progresso de leitura pelo servidor de sincronização do Komga:

  1. Dê à conta a função KOReader Sync e ative os hashes de arquivos para o KOReader nas opções da biblioteca.
  2. Gere uma chave de API na página de sua conta.
  3. No KOReader, com um livro aberto, vá em “Progress sync”, depois em “Custom sync server”, e informe https://komga.example.com/koreader.
  4. Em “Register / Login”, informe a chave de API como nome de usuário e qualquer valor como senha, que o Komga não usa.
  5. Em “Document matching method”, escolha “Binary”.

Os backups

Tudo o que o Komga sabe de seus livros fica em /config; seus livros, por sua vez, ficam em /data. Veja o que /config contém com a configuração padrão:

ElementoO que ele guarda
database.sqliteO banco principal: bibliotecas, séries, livros, metadados, usuários, progresso de leitura, coleções, listas de leitura e miniaturas geradas
tasks.sqliteAs tarefas em segundo plano pendentes
sessions.sqliteAs sessões de login, guardadas no banco por padrão desde a versão 1.30.0
lucene/O índice de busca
fonts/As fontes
logs/Os logs, entre eles komga.log
application.ymlSua configuração, se você a criou

Os bancos SQLite são copiados com o Komga parado, para uma cópia consistente. A partir da pasta do compose.yaml:

Terminal, em ~/komga
docker compose stop
tar -czf komga-config-$(date +%F).tar.gz config
docker compose start

Envie esse arquivo para fora do servidor, no ritmo de seus acréscimos e de suas leituras. Guarde também uma cópia de seus livros, com as capas que você mantém ao lado dos arquivos: é o volume mais pesado, mas muda pouco, e o rsync só envia o que é novo. Colocados no disco do servidor, esses arquivos também entram nos backups noturnos dele.

Para restaurar, pare o Komga, substitua a pasta config pela do arquivo, confira se ela ainda pertence ao usuário do compose.yaml e inicie-o de novo.

As atualizações

Com Docker Compose, a documentação dá estes comandos, executados a partir da pasta do compose.yaml. A pasta /config, montada a partir do servidor, guarda suas configurações:

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

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Komga continua sendo seu software, com as configurações dele e seus livros.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoA leitura dos logs de sua instância
KomgaAcompanhamento proativo: erros, lentidões, memória e espaço em disco identificados, correção recomendadaA instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA
As bibliotecas e os leitoresO servidor que as sustenta, monitorado e com backupAs bibliotecas, as contas, as funções e as chaves de API
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaAs cópias próprias do Komga e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO momento da virada

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.

Komga, em um servidor cuidado por nós

Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância Komga, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.

Conhecer os VPS gerenciados

Perguntas frequentes

O Komga é gratuito para uma empresa?

Sim. O Komga está sob a licença MIT: você pode usá-lo, modificá-lo e redistribuí-lo em uma empresa sem licença a comprar, desde que mantenha o aviso de copyright dele. Resta o custo do servidor em que ele roda.

De quanta memória o Komga precisa?

A documentação não fixa nenhum mínimo. Por padrão, o Java limita a memória do Komga, geralmente em torno de 1 GB. Se os logs mostrarem erros OutOfMemoryException, aumente o limite com JAVA_TOOL_OPTIONS, por exemplo -Xmx4g para 4 GB.

Como instalar o Komga com Docker Compose?

Crie um compose.yaml com a imagem gotson/komga, a porta 25600 publicada em 127.0.0.1, uma pasta config montada em /config, uma pasta data montada em /data e um usuário dono das duas, e execute docker compose up -d. Coloque então na frente da porta 25600 um proxy reverso em HTTPS.

Como criar a conta de administrador do Komga?

No primeiro acesso, o Komga pede um endereço de e-mail e uma senha: essa primeira conta recebe todas as funções. Crie-a por um túnel SSH antes de abrir o servidor ao público e crie depois as outras contas em Server Settings, Users.

Qual endereço OPDS devo informar ao meu aplicativo de leitura?

O endereço de seu servidor seguido de /opds/v2/catalog para OPDS 2, ou de /opds/v1.2/catalog para OPDS 1.2, com o endereço de e-mail e a senha de sua conta Komga.

Como sincronizar um leitor Kobo com o Komga?

Dê à conta as funções Kobo Sync e File Download, gere uma chave de API em Account Settings e substitua a linha api_endpoint do arquivo Kobo eReader.conf por https://seu-servidor/kobo/sua-chave. Apenas os livros EPUB são sincronizados.

Como fazer backup do Komga?

Pare o Komga, arquive a pasta config, inicie-o de novo e envie o arquivo para fora do servidor. Guarde também uma cópia de seus livros. Faça uma cópia logo antes de cada atualização.

Um VPS gerenciado cobre o Komga?

Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.

Entre em contato