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.
Por Simon Vasconcelos Lee
Publicado em 22 de novembro de 2026Leitura: 15 minutos
/data; o banco, o índice e os logs ficam em /config, em um disco local.gotson/komga, a porta 25600 publicada localmente atrás de um proxy reverso em HTTPS e um usuário dono das duas pastas./config para fora do servidor, guarde uma cópia de seus livros e atualize com docker compose pull.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 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.
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.
OutOfMemoryException nos logs. O limite é então aumentado com a variável JAVA_TOOL_OPTIONS, apresentada mais abaixo.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 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:
/data para os livros e as importações: a documentação pede que você coloque nela suas bibliotecas e sua pasta de importação, para que as importações criem hard links em vez de cópias. Fora do mesmo sistema de arquivos, cada importação ocupa o espaço de uma cópia./config guarda o banco principal, com as miniaturas geradas para cada livro, o banco das tarefas, o das sessões, o índice de busca e os logs, que a configuração padrão mantém por 7 dias e limita a 1 GB. Ela cresce com o tamanho de suas bibliotecas./config: os bancos SQLite nunca devem ficar em um compartilhamento de rede como CIFS ou NFS. O Komga verifica isso na inicialização e para se não for o caso.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 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:
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:
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: é a principal diferença em relação ao exemplo da documentação, que a publica em todos os endereços. A documentação recomenda fortemente o HTTPS assim que o Komga fica aberto fora de sua rede local, pois ele usa a autenticação HTTP básica. A interface passa então a ser acessada apenas pelo proxy reverso.user. A documentação pede que as pastas montadas pertençam a esse mesmo usuário: assim os problemas de permissão desaparecem./config guarda o banco e a configuração do Komga, em um disco local./data contém seus livros e sua pasta de importação. Cada biblioteca terá nela sua própria subpasta.1.x acompanha a última versão 1 publicada; 1.30.1 fixa uma versão. A documentação reserva latest para o último commit.version do exemplo da documentação foi omitida: o Docker Compose hoje a considera obsoleta e a ignora.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:
java -version
java -jar komga-1.30.1.jar
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.
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ção | O que ela permite |
|---|---|
| Administrator | Gerenciar 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 Streaming | Ler página por página, no leitor web, por exemplo |
| File Download | Baixar o arquivo de um livro |
| Kobo Sync | Sincronizar um leitor Kobo, junto com File Download |
| KOReader Sync | Sincronizar 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.
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:
command: --newpassword=YourNewPassword --reset=admin@example.org
docker compose up -d
O comando --list-users, usado da mesma forma, exibe nos logs a lista das contas.
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ável | Propriedade | Padrão | O que ela faz |
|---|---|---|---|
SERVER_PORT | server.port | 25600 | A porta da API e da interface web |
SERVER_SERVLET_CONTEXTPATH | server.servlet.context-path | / | A URL base, para servir o Komga em uma subpasta |
SPRING_SESSION_TIMEOUT | spring.session.timeout | 7 dias | A duração de uma sessão inativa, por exemplo 14d ou 24h |
KOMGA_CORS_ALLOWEDORIGINS | komga.cors.allowed-origins | Nenhuma | As origens permitidas para CORS |
LOGGING_LEVEL_ORG_GOTSON_KOMGA | logging.level.org.gotson.komga | Não definido | DEBUG 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:
- 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.
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:
X-Forwarded-For, definido ou complementado;X-Forwarded-Proto;X-Forwarded-Host.Em um subdomínio, sem URL base no Komga, o Caddy define esses cabeçalhos sozinho:
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:
example.com {
reverse_proxy /komga/* 127.0.0.1:25600
}
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:
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:
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
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.
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.
~/komga/data por biblioteca, por SFTP ou com rsync./data/manga, e clique em “Add”.rsync -av manga/ user@komga.example.com:komga/data/manga/
/data/manga e /data/comics convivem; /data e /data/manga, não.#recycle.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 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.
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.
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:
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.
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.
.kobo/Kobo/Kobo eReader.conf, com os arquivos ocultos visíveis.[OneStoreServices], substitua a linha api_endpoint pelo endereço de seu servidor seguido de sua chave.api_endpoint=https://komga.example.com/kobo/YOUR_API_KEY
api_endpoint, 443 para um endereço em HTTPS.O KOReader lê o Komga por OPDS e sincroniza o progresso de leitura pelo servidor de sincronização do Komga:
https://komga.example.com/koreader.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:
| Elemento | O que ele guarda |
|---|---|
database.sqlite | O banco principal: bibliotecas, séries, livros, metadados, usuários, progresso de leitura, coleções, listas de leitura e miniaturas geradas |
tasks.sqlite | As tarefas em segundo plano pendentes |
sessions.sqlite | As 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.yml | Sua 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:
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.
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:
docker compose pull
docker compose up -d
docker image prune
/config logo antes de cada atualização.jar, pare o Komga e depois inicie-o com o jar da nova versão.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.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | A leitura dos logs de sua instância |
| Komga | Acompanhamento proativo: erros, lentidões, memória e espaço em disco identificados, correção recomendada | A 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 leitores | O servidor que as sustenta, monitorado e com backup | As bibliotecas, as contas, as funções e as chaves de API |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | As cópias próprias do Komga e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.