Karakeep em uma VPS: seu próprio arquivo de favoritos com busca e IA

30/08/20268 min de leitura

Tropic

Karakeep em uma VPS: seu próprio arquivo de favoritos com busca e IA

Karakeep: como instalar um arquivo pessoal de favoritos em uma VPS

Salvar um link é fácil. Encontrá-lo seis meses depois é bem mais difícil, principalmente se a página mudou, desapareceu ou ficou perdida entre centenas de favoritos.

O Karakeep guarda não apenas a URL, mas também o conteúdo da página, a prévia, notas, imagens e arquivos PDF. É possível pesquisar o arquivo pelo texto, organizar os materiais em listas e marcá-los automaticamente com IA. Tudo funciona na sua própria VPS, e a conexão de um modelo de linguagem é opcional.

A seguir, veremos os recursos do Karakeep, os requisitos do servidor e a instalação no Ubuntu 24.04 com Docker Compose, HTTPS e backups.

Karakeep em sete etapas

Criar uma VPS Linux e apontar para ela um subdomínio, como keep.example.com.
Instalar o Docker Engine e o Docker Compose.
Baixar o arquivo oficial docker-compose.yml.
Gerar os segredos e iniciar o Karakeep, o Chrome e o Meilisearch.
Fechar a porta interna 3000 e ativar HTTPS por meio do Caddy.
Criar a primeira conta e depois desativar o cadastro público.
Instalar a extensão do navegador ou o aplicativo móvel e importar os favoritos.

Não é necessário ter uma chave de IA para iniciar o serviço. Sem ela, o salvamento de páginas, as listas, as notas, o OCR e a busca em texto completo continuam funcionando. Apenas as tags automáticas e os resumos deixam de ser gerados.

O que é o Karakeep

O Karakeep é um aplicativo auto-hospedado e de código aberto para guardar links, notas de texto, imagens e PDFs em uma única biblioteca. Antes, o projeto se chamava Hoarder.

O nome vem da palavra árabe karakeeb, usada para objetos espalhados que parecem bagunça, mas podem ter um valor oculto. É uma descrição precisa de uma coleção comum de favoritos: há muito conteúdo útil, mas encontrar o item certo pode ser difícil.

Depois que um link é adicionado, o Karakeep obtém o título e a descrição, extrai o texto legível, cria uma prévia e, quando necessário, salva uma cópia local da página.

Recurso	Favoritos do navegador	Karakeep
O que é armazenado	URL e título	Texto, prévia, notas e anexos
Busca	Por título e endereço	Por conteúdo, tags e notas
Se a página desaparecer	Resta uma URL que não funciona	Permanecem o texto, uma captura ou um arquivo completo
Organização	Pastas	Tags, listas manuais e listas inteligentes
Acesso	No navegador	Web, extensões, iOS e Android
Servidor	Perfil do navegador ou sua nuvem	Sua VPS ou servidor doméstico

Principais recursos do Karakeep

Links, notas, imagens e PDFs

Cada item pode ser um link, uma nota de texto ou um arquivo enviado. O OCR extrai texto de imagens e PDFs, fazendo com que eles também apareçam nas buscas. É possível anexar uma nota, uma citação ou um arquivo adicional ao material.

Busca pelo conteúdo

O Meilisearch indexa o texto salvo, as notas e os metadados. Não é preciso lembrar o título exato: uma frase ou um tema já é suficiente. Quando os embeddings estão configurados, também fica disponível a busca semântica pelo significado.

Listas inteligentes e colaborativas

Um mesmo item pode fazer parte de várias listas ao mesmo tempo sem ser duplicado. A lista pode permanecer privada, ser compartilhada por link ou ser editada em conjunto com outros usuários.

Uma lista inteligente é uma consulta de busca salva que se atualiza automaticamente. Por exemplo, ela pode mostrar todos os materiais com a tag ai adicionados durante a última semana.

Arquivamento de páginas

Por padrão, o Karakeep salva o texto extraído e uma captura da parte visível da página. Também é possível ativar uma captura completa, um PDF ou um arquivo HTML autônomo. Isso protege a biblioteca contra links quebrados, mas aumenta o uso do disco.

Páginas que exigem autenticação, usam proteções complexas contra bots ou funcionam como aplicativos interativos podem não ser salvas por completo. Para materiais importantes, é melhor enviar também um PDF ou arquivo separado.

Marcação opcional com IA

O Karakeep pode gerar tags e resumos curtos por meio de uma API externa compatível com a OpenAI ou de um modelo local do Ollama. Sem IA, o aplicativo continua sendo um gerenciador de favoritos completo.

Um modelo local não envia os materiais para um provedor externo, mas exige muito mais RAM. Por isso, o Ollama costuma ser hospedado separadamente da instância principal do Karakeep.

Requisitos de servidor do Karakeep

A documentação oficial não define um mínimo fixo de CPU e RAM. A instalação completa inclui três contêineres:

o Karakeep armazena o banco de dados e fornece a interface;
o Chrome em modo headless abre as páginas, executa JavaScript e cria capturas de tela;
o Meilisearch indexa a biblioteca.

Uma configuração prática para um usuário sem LLM local é:

2 vCPU;
2 GB de RAM;
20–30 GB em SSD ou NVMe;
Ubuntu 24.04 LTS;
IP público e domínio.

Para vários usuários, uma importação grande, muitos feeds RSS e arquivos PDF, 4 GB de RAM oferecem mais conforto. O tamanho do disco depende do modo de arquivamento: o texto ocupa pouco espaço, enquanto capturas completas, PDFs e vídeos podem aumentar rapidamente a biblioteca.

Como instalar o Karakeep em uma VPS

Este exemplo usa Ubuntu 24.04 e o subdomínio keep.example.com.

1. Configure o DNS e o firewall

Crie um registro DNS A apontando para o endereço IP do servidor e depois conecte-se por SSH:

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Não feche a sessão SSH atual até confirmar que uma nova conexão funciona.

2. Instale o Docker

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
docker compose version

3. Baixe a configuração do Karakeep

mkdir -p /opt/karakeep
cd /opt/karakeep

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

Gere dois segredos diferentes:

openssl rand -base64 36
openssl rand -base64 36 | tr -dc 'A-Za-z0-9'

Crie /opt/karakeep/.env:

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=INSIRA_O_PRIMEIRO_SEGREDO
MEILI_MASTER_KEY=INSIRA_O_SEGUNDO_SEGREDO
NEXTAUTH_URL=https://keep.example.com
DISABLE_SIGNUPS=false
DB_WAL_MODE=true
RATE_LIMITING_ENABLED=true

Não publique o arquivo .env: o primeiro segredo assina os tokens de autenticação, e o segundo protege o Meilisearch.

4. Feche a porta interna

No arquivo docker-compose.yml, substitua:

ports:
  - 3000:3000

por:

ports:
  - 127.0.0.1:3000:3000

Assim, a porta 3000 não ficará acessível diretamente pela internet.

5. Inicie os contêineres

cd /opt/karakeep
docker compose up -d
docker compose ps

Os serviços web, chrome e meilisearch devem estar em execução. Para exibir os logs, use:

docker compose logs --tail=200

6. Ative o HTTPS

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
keep.example.com {
    reverse_proxy 127.0.0.1:3000
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Se o DNS estiver configurado e as portas 80 e 443 estiverem abertas, o Caddy obterá automaticamente um certificado TLS. Depois disso, abra https://keep.example.com.

7. Crie o administrador e feche os cadastros

O primeiro usuário cadastrado se torna administrador automaticamente. Depois de criar a conta, defina no arquivo .env:

DISABLE_SIGNUPS=true

Aplique a alteração:

cd /opt/karakeep
docker compose up -d

O administrador ainda poderá criar outras contas manualmente.

Importação, extensões e aplicativos móveis

O Karakeep oferece extensões para Chrome, Firefox e Safari, além de aplicativos para iOS e Android. No telefone, um link pode ser enviado para o arquivo pelo menu de compartilhamento do sistema.

Os favoritos existentes podem ser importados de um arquivo HTML padrão do navegador, do Pocket, do Omnivore e de outros serviços compatíveis. É melhor adicionar um arquivo grande em lotes: o servidor precisa abrir as páginas, extrair o texto, criar capturas e montar o índice de busca.

Como ativar a IA e o arquivamento completo

Para usar a OpenAI, adicione ao arquivo .env:

OPENAI_API_KEY=SUA_CHAVE_DE_API

Outro serviço compatível com a OpenAI também pode exigir OPENAI_BASE_URL. Para um modelo local, use OLLAMA_BASE_URL com um endereço acessível a partir do contêiner.

A cópia local completa da página é ativada separadamente:

CRAWLER_FULL_PAGE_ARCHIVE=true

Também estão disponíveis CRAWLER_FULL_PAGE_SCREENSHOT=true e CRAWLER_STORE_PDF=true. Não ative todos os modos sem necessidade, pois eles aumentam consideravelmente o uso do disco. Depois de alterar o arquivo .env, execute docker compose up -d.

Segurança, atualizações e backups

O rastreador do Karakeep abre, a partir da rede do seu servidor, os endereços salvos pelos usuários. Por isso, não deixe o cadastro público aberto e conceda acesso apenas a pessoas confiáveis. Há uma proteção básica contra SSRF, mas, para um serviço público, o projeto oficial recomenda isolar o navegador ou encaminhá-lo por um proxy restrito.

Use também HTTPS e senhas fortes, não exponha a porta 3000 e atualize os contêineres regularmente:

cd /opt/karakeep
docker compose up --pull always -d

O banco de dados principal e os materiais salvos ficam no volume Docker chamado data. Pare os contêineres antes de fazer a cópia:

mkdir -p /var/backups/karakeep
cd /opt/karakeep
docker compose stop

docker run --rm \
  -v karakeep_data:/source:ro \
  -v /var/backups/karakeep:/backup \
  alpine sh -c 'tar czf /backup/data-$(date +%F).tar.gz -C /source .'

cp .env docker-compose.yml /var/backups/karakeep/
docker compose start

O nome karakeep_data pressupõe que o diretório do projeto seja /opt/karakeep; confirme com docker volume ls. O índice de busca do Meilisearch pode ser recriado, mas, para uma biblioteca grande, também é útil copiar o volume karakeep_meilisearch.

Envie o arquivo de /var/backups/karakeep para outro servidor, um NAS ou um armazenamento de objetos. Uma cópia na mesma VPS não protege contra falha do disco nem contra a exclusão da máquina virtual.

Qual VPS escolher para o Karakeep

Para uma biblioteca pessoal sem Ollama, uma VPS Linux com 2 vCPU, 2 GB de RAM e 20–30 GB de NVMe é suficiente. Para uma importação grande, vários usuários e arquivamento completo, escolha 4 GB de RAM e um disco maior.

O Karakeep pode ser executado em uma VPS da tropic.host: um IP permanente simplifica a configuração do domínio, enquanto o NVMe é útil para SQLite, o índice de busca e muitos arquivos pequenos. Os recursos podem ser ampliados conforme o arquivo cresce.

Calcule separadamente os recursos do Ollama local: até mesmo um modelo de linguagem pequeno pode exigir mais memória do que toda a pilha principal do Karakeep.

Conclusão

O Karakeep transforma links espalhados em uma biblioteca pessoal pesquisável. Ele salva páginas, notas, imagens e PDFs e oferece OCR, listas, extensões, aplicativos móveis e marcação opcional com IA.

Uma VPS pequena, Docker Compose, um domínio e HTTPS são suficientes para começar. Depois da instalação, feche os cadastros, monitore o uso do disco e mantenha um backup externo.

FAQ

O Karakeep é gratuito?

A versão auto-hospedada tem código aberto e não exige assinatura obrigatória. Os custos são da VPS, do domínio, do armazenamento de backup e, quando necessário, de uma API externa de IA.

É necessário ter uma chave de API para usar o Karakeep?

Não. O salvamento e a indexação de materiais, as listas, as notas, o OCR e a busca em texto completo funcionam sem IA. Um modelo é necessário para tags automáticas, resumos e recursos relacionados.

De quanta RAM o Karakeep precisa?

Um ponto de partida prático para um usuário sem Ollama é 2 GB de RAM. Para importações grandes, vários usuários e processamento intenso, 4 GB são mais confortáveis.

Posso importar favoritos do navegador ou do Pocket?

Sim. O Karakeep aceita o arquivo HTML padrão de favoritos do navegador, Pocket, Omnivore e vários outros formatos. Depois da importação, ele processa as páginas e as adiciona à busca.

O artigo continuará disponível se o site original desaparecer?

O Karakeep salva o texto extraído e uma captura de tela e, quando o arquivamento completo está ativado, também uma cópia local ou um PDF. Páginas que exigem autenticação e aplicativos web complexos podem ser salvos apenas parcialmente.

Voltar ao Blog