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.
Por Simon Vasconcelos Lee
Publicado a 22 de novembro de 2026Leitura: 15 minutos
/data; a base de dados, o índice e os registos ficam em /config, num disco local.gotson/komga, a porta 25600 publicada localmente atrás de um proxy inverso em HTTPS, e um utilizador proprietário das duas pastas./config para fora do servidor, guarde uma cópia dos seus livros e atualize com docker compose pull.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 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.
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.
OutOfMemoryException nos registos. O limite sobe-se então com a variável JAVA_TOOL_OPTIONS, apresentada mais abaixo.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».
É 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:
/data para os livros e as importações: a documentação pede que coloque lá as suas bibliotecas e a sua pasta de importação, para que as importações criem ligações físicas em vez de cópias. Fora do mesmo sistema de ficheiros, cada importação ocupa o espaço de uma cópia./config guarda a base de dados principal, com as miniaturas geradas para cada livro, a base de dados das tarefas, a das sessões, o índice de pesquisa e os registos, que a configuração predefinida guarda durante 7 dias e limita a 1 GB. Cresce com o tamanho das suas bibliotecas./config: as bases de dados SQLite nunca devem estar numa partilha de rede como CIFS ou NFS. O Komga verifica-o no arranque e para se não for o caso.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 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:
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:
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 vivamente o HTTPS assim que o Komga fica aberto fora da sua rede local, porque utiliza a autenticação HTTP básica. A interface passa então a ser acessível apenas através do proxy inverso.user. A documentação pede que as pastas montadas pertençam a esse mesmo utilizador: os problemas de permissões desaparecem assim./config guarda a base de dados e a configuração do Komga, num disco local./data contém os seus livros e a sua pasta de importação. Cada biblioteca terá lá a 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 é omitida: o Docker Compose considera-a hoje obsoleta e ignora-a.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:
java -version
java -jar komga-1.30.1.jar
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.
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 permite |
|---|---|
| Administrator | Gerir 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 Streaming | Ler página a página, no leitor web, por exemplo |
| File Download | Transferir o ficheiro de um livro |
| Kobo Sync | Sincronizar um leitor Kobo, juntamente com File Download |
| KOReader Sync | Sincronizar 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.
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:
command: --newpassword=YourNewPassword --reset=admin@example.org
docker compose up -d
O comando --list-users, utilizado da mesma forma, apresenta nos registos a lista das contas.
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ável | Propriedade | Predefinição | Para que serve |
|---|---|---|---|
SERVER_PORT | server.port | 25600 | A porta da API e da interface web |
SERVER_SERVLET_CONTEXTPATH | server.servlet.context-path | / | O URL de base, para servir o Komga numa 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 autorizadas para CORS |
LOGGING_LEVEL_ORG_GOTSON_KOMGA | logging.level.org.gotson.komga | Não definido | DEBUG 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:
- 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.
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:
X-Forwarded-For, definido ou completado;X-Forwarded-Proto;X-Forwarded-Host.Num subdomínio, sem URL de base no Komga, o Caddy define estes cabeçalhos por si próprio:
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:
example.com {
reverse_proxy /komga/* 127.0.0.1:25600
}
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:
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:
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, 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.
~/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 coexistem; /data e /data/manga, não.#recycle.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.
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.
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.
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:
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.
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.
.kobo/Kobo/Kobo eReader.conf, com os ficheiros ocultos visíveis.[OneStoreServices], substitua a linha api_endpoint pelo endereço do seu servidor seguido da 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 seu progresso de leitura através do servidor de sincronização do Komga:
https://komga.example.com/koreader.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:
| Elemento | O que guarda |
|---|---|
database.sqlite | A base de dados principal: bibliotecas, séries, livros, metadados, utilizadores, 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 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.yml | A 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:
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.
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:
docker compose pull
docker compose up -d
docker image prune
/config mesmo antes de cada atualização.jar, pare o Komga e depois arranque-o com o jar da nova versão.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.
| Assunto | As nossas equipas | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, intervenções no servidor incluídas | O momento que convém à sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamada | A leitura dos registos da sua instância |
| Komga | Acompanhamento proativo: erros, lentidão, memória e espaço em disco identificados, correção recomendada | A 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 leitores | O servidor que as suporta, vigiado e com cópias de segurança | As bibliotecas, as contas, as funções e as chaves de API |
| As cópias de segurança | Todas as noites, cifradas e guardadas fora da máquina; restauro incluído | As cópias próprias do Komga e o pedido de restauro, quando precisar |
| A migração | O seu servidor atual migrado, oferecido | O 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Simafri
Vamos falar do seu projeto
Diga-nos em poucas palavras o que precisa: respondemos-lhe rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o email? Escreva-nos para support@simafri.com.