Alojar Komga num VPS gerido: a sua banda desenhada e mangá no seu servidor

Alojar Komga num VPS gerido é ler a sua banda desenhada, os seus mangás e os seus livros digitais a partir de uma máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Komga é um servidor multimédia livre sob licença MIT. Este guia segue a sua documentação oficial: a memória e o armazenamento a prever, a instalação com o Docker Compose, a primeira conta, a configuração, o HTTPS, as bibliotecas, a leitura por OPDS, Kobo e KOReader, as cópias de segurança e as atualizações.

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

Todos os guias

O essencial

  1. A licença MIT permite utilizar, modificar e redistribuir livremente o Komga, numa empresa como em qualquer outro lado, desde que mantenha o seu aviso de direitos de autor.
  2. O armazenamento dimensiona-se pela sua coleção, guardada em /data; a base de dados, o índice e os registos ficam em /config, num disco local.
  3. Instale-o com o Docker Compose: a imagem gotson/komga, a porta 25600 publicada localmente atrás de um proxy inverso em HTTPS, e um utilizador proprietário das duas pastas.
  4. A primeira conta criada torna-se a de administrador: crie-a através de 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 dos seus livros e atualize com docker compose pull.

O que faz o Komga

O Komga é um servidor multimédia para a sua banda desenhada, os seus comics, os seus mangás, as suas revistas e os seus livros digitais. Indica-lhe as pastas onde estão os seus ficheiros, e ele organiza-os em bibliotecas, séries e livros, e depois serve-os a um navegador ou a uma aplicação de leitura. Funciona em qualquer lado onde funcione o Java ou o Docker.

O que a licença MIT permite

O Komga é publicado sob a licença MIT, em nome de Gauthier Roebroeck. Concede, gratuitamente, o direito de utilizar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender cópias do software. Pode, portanto, pô-lo a funcionar para si, para a sua família, para a sua associação ou para a sua empresa, sem licença para comprar.

A única condição é manter o aviso de direitos de autor e o texto da licença em todas as cópias ou partes substanciais do software. O texto fornece o software «tal como está», sem garantia.

Memória, processador e armazenamento: dimensionar o servidor

A documentação não fixa nenhuma configuração mínima. Dá, em contrapartida, o que conta para dimensionar o servidor: a memória da máquina virtual Java, as tarefas que solicitam o processador e, sobretudo, o espaço ocupado pelos seus ficheiros.

A memória do Java

O processador

O processador trabalha sobretudo durante os varrimentos e as análises das bibliotecas. Para cada uma, a documentação avisa que o cálculo das impressões digitais dos ficheiros, das impressões digitais das páginas e das impressões digitais para o KOReader, tal como a análise das dimensões das páginas, pode exigir muitos recursos numa biblioteca grande. O número de threads dedicadas às tarefas em segundo plano define-se em «Server Settings».

O armazenamento dos seus livros

É a rubrica mais pesada, e mede-se do seu lado: o volume da sua coleção, mais o espaço para os livros que prevê acrescentar. O Komga lê os seus ficheiros onde estão e não os copia. Alguns pontos da documentação mudam o cálculo:

Num VPS gerido, descreva-nos a sua coleção, o seu volume, o seu ritmo de crescimento e o número de leitores, e recomendamos-lhe o tamanho adequado.

A instalação com o Docker Compose

A documentação publica a imagem gotson/komga no Docker Hub e no ghcr.io, para processadores amd64, arm64 e arm. Num servidor com o Docker instalado, crie uma pasta para o Komga, com as suas duas subpastas, e anote o seu identificador de utilizador:

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

Coloque nela este compose.yaml, tirado do exemplo da documentação. Substitua 1000:1000 pelos valores uid e gid apresentados por id, e TZ pelo 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 ficheiro jar

A outra via da documentação para um servidor Linux é o ficheiro jar de cada versão, publicado no GitHub. Exige o Java 17 ou mais recente, e guarda a sua configuração em ~/.komga:

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

A primeira conta e os utilizadores

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

Terminal, no 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 permite
AdministratorGerir as bibliotecas, os utilizadores e as coleções, editar os metadados, lançar os varrimentos, as análises e as atualizações de metadados
Page StreamingLer página a página, no leitor web, por exemplo
File DownloadTransferir o ficheiro de um livro
Kobo SyncSincronizar um leitor Kobo, juntamente com File Download
KOReader SyncSincronizar o progresso de leitura com o KOReader

Eliminar um utilizador apaga todo o seu progresso de leitura, sem volta atrás: uma cópia de /config feita mesmo antes permite-lhe manter o controlo.

Repor uma palavra-passe pela linha de comandos

A documentação acrescenta o comando ao compose.yaml, no serviço komga; o Komga aplica a alteração e depois arranca 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, utilizado da mesma forma, apresenta nos registos a lista das contas.

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

O Komga tem valores predefinidos para cada definição: a configuração só serve para mudar o seu comportamento. Faz-se com variáveis de ambiente, a via mais simples com o Docker Compose, ou com um ficheiro 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 hífenes e passe para maiúsculas.

VariávelPropriedadePredefiniçãoPara que serve
SERVER_PORTserver.port25600A porta da API e da interface web
SERVER_SERVLET_CONTEXTPATHserver.servlet.context-path/O URL de base, para servir o Komga numa 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 autorizadas para CORS
LOGGING_LEVEL_ORG_GOTSON_KOMGAlogging.level.org.gotson.komgaNão definidoDEBUG para registos detalhados

A porta e o URL de base também se definem em «Server Settings», e essa definição prevalece então sobre a configuração. Para a memória do Java, acrescente a variável JAVA_TOOL_OPTIONS à secçã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 da base de dados. Com o Docker, mantenha-o em /config/database.sqlite, o seu valor predefinido: noutro sítio, a base de dados seria criada dentro do contentor e perdida quando este fosse recriado. Guarde do exemplo apenas as linhas de que precisa.

O HTTPS e o proxy inverso

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

Com o Caddy

Num subdomínio, sem URL de base no Komga, o Caddy define estes cabeçalhos por si próprio:

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

Numa subpasta, defina primeiro o URL de 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 Nginx da documentação transmite também as ligações WebSocket. Acrescente este bloco map à secçã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 definições do exemplo da documentação, na porta 80 para deixar o Certbot instalar o HTTPS. A linha X-Forwarded-Host é acrescentada, já que a lista de cabeçalhos da documentação a pede:

Bloco 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, os varrimentos e as importações

Uma biblioteca é um grupo de livros, arrumado sob uma pasta raiz. O Komga cria uma série para cada subpasta, a qualquer profundidade, e um livro para cada ficheiro, colocado na série da sua pasta-mãe. Os metadados dos ficheiros EPUB e dos ficheiros ComicInfo.xml contidos nos arquivos prevalecem sobre os nomes das pastas e dos ficheiros.

  1. Coloque os seus ficheiros no servidor, numa 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 sua pasta raiz com «Browse», por exemplo /data/manga, e clique em «Add».
Terminal, no seu computador
rsync -av manga/ user@komga.example.com:komga/data/manga/

O lixo

Um livro cujo ficheiro desaparece passa para o lixo, marcado como «Unavailable», em vez de ser apagado: os seus metadados, o seu progresso de leitura e as suas listas regressam se o ficheiro reaparecer no seu lugar. Pode, portanto, renomear e mover os seus ficheiros sem perder nada. O lixo esvazia-se à mão, ou depois de cada varrimento se ativar essa opção, que então apaga os elementos de imediato.

A importação de livros

O ecrã «Import», «Books» arruma nas suas séries livros que estão noutra pasta do servidor, /data/import, por exemplo. Para cada ficheiro, escolhe a série de destino, o número e o nome; um número já ocupado propõe substituir o livro existente, mostrando os dois lado a lado. O Komga move os ficheiros, ou cria ligações físicas quando o sistema de ficheiros o permite, e copia-os caso contrário.

Mudar a pasta raiz de uma biblioteca para um caminho sem relação com o anterior apaga as suas séries, os seus livros e o seu progresso de leitura. As perguntas frequentes descrevem como a mover: impressões digitais dos ficheiros ativas, esvaziamento automático do lixo desativado, e depois um varrimento antes da mudança.

Ler em qualquer lado: OPDS, Kobo e KOReader

O leitor web abre-se no navegador, no endereço do servidor. Para uma aplicação ou um leitor de livros digitais, o Komga oferece três portas, todas a servir em HTTPS.

OPDS

O Komga funciona com qualquer aplicação OPDS, na versão 1 ou 2. Indique à aplicação um destes endereços, e depois o endereço de e-mail e a palavra-passe da 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 pesquisa por série, através do OpenSearch, e a leitura página a página sem transferência, através da extensão OPDS PSE. A documentação mantém uma lista das aplicações testadas, em Android, iOS e noutros sistemas, com o que cada uma suporta.

A sincronização Kobo

O seu leitor Kobo sincroniza-se com o Komga em vez dos servidores oficiais da Kobo. Os livros EPUB de todas as bibliotecas chegam com os seus metadados e a sua capa, convertidos em KEPUB em tempo real pelo Kepubify, incluído na imagem Docker. O progresso de leitura sincroniza-se nos dois sentidos.

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

A sincronização KOReader

O KOReader lê o Komga por OPDS, e sincroniza o seu progresso de leitura através do servidor de sincronização do Komga:

  1. Dê à conta a função KOReader Sync, e ative as impressões digitais dos ficheiros para o KOReader nas opções da biblioteca.
  2. Gere uma chave de API na página da sua conta.
  3. No KOReader, com um livro aberto, vá a «Progress sync», depois a «Custom sync server», e introduza https://komga.example.com/koreader.
  4. Em «Register / Login», introduza a chave de API como nome de utilizador, e um valor qualquer como palavra-passe, que o Komga não utiliza.
  5. Em «Document matching method», escolha «Binary».

As cópias de segurança

Tudo o que o Komga sabe dos seus livros fica em /config; os seus livros, esses, ficam em /data. Eis o que /config contém com a configuração predefinida:

ElementoO que guarda
database.sqliteA base de dados principal: bibliotecas, séries, livros, metadados, utilizadores, progresso de leitura, coleções, listas de leitura e miniaturas geradas
tasks.sqliteAs tarefas em segundo plano pendentes
sessions.sqliteAs sessões de início de sessão, guardadas na base de dados por predefinição desde a versão 1.30.0
lucene/O índice de pesquisa
fonts/Os tipos de letra
logs/Os registos, incluindo komga.log
application.ymlA sua configuração, se a tiver criado

As bases de dados SQLite copiam-se com o Komga parado, para uma cópia coerente. 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 este arquivo para fora do servidor, ao ritmo dos seus acréscimos e das suas leituras. Guarde também uma cópia dos seus livros, com as capas que guarda ao lado dos ficheiros: é o volume mais pesado, mas muda pouco, e o rsync só envia o que é novo. Colocados no disco do servidor, estes arquivos entram também nas suas cópias de segurança noturnas.

Para restaurar, pare o Komga, substitua a pasta config pela do arquivo, verifique que continua a pertencer ao utilizador do compose.yaml, e volte a arrancá-lo.

As atualizações

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

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

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Komga continua a ser o seu software, com as suas definições e os seus livros.

AssuntoAs nossas equipasVocê
O servidorAtualizações do sistema e de segurança, intervenções no servidor incluídasO momento que convém à sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamadaA leitura dos registos da sua instância
KomgaAcompanhamento proativo: erros, lentidão, memória e espaço em disco identificados, correção recomendadaA sua instalação, as suas atualizações e as suas definições, que aplica diretamente ou com o seu assistente de IA
As bibliotecas e os leitoresO servidor que as suporta, vigiado e com cópias de segurançaAs bibliotecas, as contas, as funções e as chaves de API
As cópias de segurançaTodas as noites, cifradas e guardadas fora da máquina; restauro incluídoAs cópias próprias do Komga e o pedido de restauro, quando precisar
A migraçãoO seu servidor atual migrado, oferecidoO momento da mudança

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.

O Komga, num servidor mantido por si

Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância Komga, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.

Descobrir os VPS geridos

Perguntas frequentes

O Komga é gratuito para uma empresa?

Sim. O Komga está sob licença MIT: pode utilizá-lo, modificá-lo e redistribuí-lo numa empresa sem licença para comprar, desde que mantenha o seu aviso de direitos de autor. Resta o custo do servidor que o faz funcionar.

De quanta memória precisa o Komga?

A documentação não fixa nenhum mínimo. Por predefinição, o Java limita a memória do Komga, normalmente perto de 1 GB. Se os registos mostrarem erros OutOfMemoryException, suba o limite com JAVA_TOOL_OPTIONS, por exemplo -Xmx4g para 4 GB.

Como instalar o Komga com o 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 utilizador proprietário das duas, e execute docker compose up -d. Coloque depois um proxy inverso em HTTPS à frente da porta 25600.

Como criar a conta de administrador do Komga?

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

Que endereço OPDS devo dar à minha aplicação de leitura?

O endereço do 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 palavra-passe da 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 depois a linha api_endpoint do ficheiro Kobo eReader.conf por https://seu-servidor/kobo/sua-chave. Só os livros EPUB são sincronizados.

Como fazer a cópia de segurança do Komga?

Pare o Komga, arquive a pasta config, volte a arrancá-lo e envie o arquivo para fora do servidor. Guarde também uma cópia dos seus livros. Faça uma cópia mesmo antes de cada atualização.

Um VPS gerido cobre o Komga?

Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.

Contacte-nos