Karakeep: installare un archivio personale di preferiti su un VPS

Salvare un link è facile. Ritrovarlo sei mesi dopo è molto più difficile, soprattutto se la pagina è cambiata, è scomparsa o si è persa tra centinaia di preferiti.

Karakeep conserva non soltanto l’URL, ma anche il contenuto della pagina, l’anteprima, le note, le immagini e i PDF. È possibile cercare nell’archivio per testo, organizzare gli elementi in elenchi e assegnare automaticamente tag con l’IA. Il servizio funziona sul proprio VPS e il collegamento di un modello linguistico è facoltativo.

Di seguito esamineremo le funzioni di Karakeep, i requisiti del server e l’installazione su Ubuntu 24.04 tramite Docker Compose, con HTTPS e backup.

Karakeep in sette passaggi

1. Creare un VPS Linux e indirizzarvi un sottodominio, ad esempio keep.example.com.
2. Installare Docker Engine e Docker Compose.
3. Scaricare il file ufficiale docker-compose.yml.
4. Generare i segreti e avviare Karakeep, Chrome e Meilisearch.
5. Chiudere la porta interna 3000 e attivare HTTPS tramite Caddy.
6. Creare il primo account e poi disattivare la registrazione pubblica.
7. Installare l’estensione del browser o l’app mobile e importare i preferiti.

Per avviare il servizio non è necessaria una chiave IA. Senza di essa continueranno a funzionare il salvataggio delle pagine, gli elenchi, le note, l’OCR e la ricerca full-text. Non verranno generati soltanto i tag automatici e i riepiloghi.

Che cos’è Karakeep

Karakeep è un’applicazione self-hosted e open source che consente di conservare link, note testuali, immagini e PDF in un’unica libreria. In precedenza il progetto si chiamava Hoarder.

Il nome deriva dalla parola araba karakeeb, usata per indicare oggetti sparsi che sembrano disordinati, ma possono nascondere un valore. È una descrizione precisa di una normale raccolta di preferiti: i contenuti utili sono molti, ma trovare quello giusto è difficile.

Dopo l’aggiunta di un link, Karakeep recupera titolo e descrizione, estrae il testo leggibile, crea un’anteprima e, se necessario, salva una copia locale della pagina.

Funzione	Preferiti del browser	Karakeep
Contenuto salvato	URL e titolo	Testo, anteprima, note e allegati
Ricerca	Per titolo e indirizzo	Per contenuto, tag e note
Se la pagina scompare	Rimane un URL non funzionante	Restano il testo, uno screenshot o un archivio completo
Organizzazione	Cartelle	Tag, elenchi manuali ed elenchi intelligenti
Accesso	Nel browser	Web, estensioni, iOS e Android
Server	Profilo del browser o relativo cloud	Il proprio VPS o server domestico

Funzioni principali di Karakeep

Link, note, immagini e PDF

Ogni elemento può essere un link, una nota testuale o un file caricato. L’OCR estrae il testo da immagini e PDF, rendendo ricercabili anche questi contenuti. A un materiale si possono allegare una nota, una citazione o un file aggiuntivo.

Ricerca nei contenuti

Meilisearch indicizza il testo salvato, le note e i metadati. Non è necessario ricordare il titolo esatto: basta una frase o un argomento. Quando sono configurati gli embedding, è disponibile anche la ricerca semantica basata sul significato.

Elenchi intelligenti e condivisi

Uno stesso elemento può appartenere contemporaneamente a più elenchi senza essere duplicato. Un elenco può rimanere privato, essere condiviso tramite link o modificato insieme ad altri utenti.

Un elenco intelligente è una query di ricerca salvata che si aggiorna automaticamente. Per esempio, può mostrare tutti i materiali con il tag ai aggiunti durante l’ultima settimana.

Archiviazione delle pagine

Per impostazione predefinita, Karakeep salva il testo estratto e uno screenshot della parte visibile della pagina. È inoltre possibile attivare un’acquisizione completa, un PDF o un archivio HTML autonomo. Questo protegge la libreria dai link non più validi, ma aumenta l’uso del disco.

Le pagine che richiedono autenticazione, adottano protezioni complesse contro i bot o funzionano come applicazioni interattive potrebbero non essere salvate integralmente. Per i materiali importanti è preferibile caricare anche un PDF o un file separato.

Etichettatura IA facoltativa

Karakeep può generare tag e brevi riepiloghi tramite un’API esterna compatibile con OpenAI o un modello Ollama locale. Senza IA, l’applicazione rimane un gestore di preferiti completo.

Un modello locale non invia i materiali a un fornitore esterno, ma richiede molta più RAM. Per questo motivo Ollama viene spesso ospitato separatamente dall’istanza principale di Karakeep.

Requisiti del server per Karakeep

La documentazione ufficiale non stabilisce un minimo fisso di CPU e RAM. Un’installazione completa comprende tre container:

• Karakeep conserva il database e fornisce l’interfaccia;
• Chrome in modalità headless apre le pagine, esegue JavaScript e crea screenshot;
• Meilisearch indicizza la libreria.

Una configurazione pratica per un utente senza LLM locale è:

• 2 vCPU;
• 2 GB di RAM;
• 20–30 GB su SSD o NVMe;
• Ubuntu 24.04 LTS;
• un IP pubblico e un dominio.

Per più utenti, una grande importazione, numerosi feed RSS e PDF, 4 GB di RAM sono più comodi. Lo spazio su disco dipende dalla modalità di archiviazione: il testo occupa poco, mentre screenshot completi, PDF e video possono far crescere rapidamente la libreria.

Come installare Karakeep su un VPS

In questo esempio vengono utilizzati Ubuntu 24.04 e il sottodominio keep.example.com.

1. Configurare DNS e firewall

Create un record DNS A che punti all’indirizzo IP del server, quindi collegatevi tramite SSH:

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

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

Non chiudete la sessione SSH corrente finché non avete verificato che una nuova connessione funzioni.

2. Installare 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. Scaricare la configurazione di 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

Generate due segreti differenti:

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

Create /opt/karakeep/.env:

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

Non pubblicate .env: il primo segreto firma i token di autenticazione, mentre il secondo protegge Meilisearch.

4. Chiudere la porta interna

Nel file docker-compose.yml, sostituite:

ports:
  - 3000:3000

con:

ports:
  - 127.0.0.1:3000:3000

In questo modo la porta 3000 non sarà accessibile direttamente da Internet.

5. Avviare i container

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

I servizi web, chrome e meilisearch devono essere in esecuzione. I log vengono visualizzati con il comando:

docker compose logs --tail=200

6. Attivare 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 il DNS è configurato e le porte 80 e 443 sono aperte, Caddy otterrà automaticamente un certificato TLS. Aprite quindi https://keep.example.com.

7. Creare un amministratore e chiudere le registrazioni

Il primo utente registrato diventa automaticamente amministratore. Dopo aver creato l’account, impostate in .env:

DISABLE_SIGNUPS=true

Applicate la modifica:

cd /opt/karakeep
docker compose up -d

L’amministratore potrà comunque creare manualmente altri account.

Importazione, estensioni e applicazioni mobili

Karakeep offre estensioni per Chrome, Firefox e Safari, oltre ad applicazioni per iOS e Android. Sul telefono, un link può essere inviato all’archivio tramite il menu di condivisione del sistema.

I preferiti esistenti possono essere importati da un normale file HTML del browser, da Pocket, Omnivore e altri servizi supportati. È meglio aggiungere un archivio di grandi dimensioni a gruppi: il server deve aprire le pagine, estrarre il testo, creare gli screenshot e costruire l’indice di ricerca.

Come attivare l’IA e l’archiviazione completa

Per OpenAI, aggiungete a .env:

OPENAI_API_KEY=LA_VOSTRA_CHIAVE_API

Un altro servizio compatibile con OpenAI potrebbe richiedere anche OPENAI_BASE_URL. Per un modello locale si utilizza OLLAMA_BASE_URL con un indirizzo raggiungibile dal container.

La copia locale completa di una pagina si attiva separatamente:

CRAWLER_FULL_PAGE_ARCHIVE=true

Sono disponibili anche CRAWLER_FULL_PAGE_SCREENSHOT=true e CRAWLER_STORE_PDF=true. Non attivate tutte le modalità senza necessità, perché aumentano sensibilmente l’uso del disco. Dopo aver modificato .env, eseguite docker compose up -d.

Sicurezza, aggiornamenti e backup

Il crawler di Karakeep apre gli indirizzi salvati dagli utenti dalla rete del vostro server. Per questo motivo, non lasciate aperta la registrazione pubblica e concedete l’accesso soltanto a persone fidate. È presente una protezione SSRF di base, ma per un servizio pubblico il progetto ufficiale consiglia di isolare il browser o instradarlo attraverso un proxy con restrizioni.

Utilizzate inoltre HTTPS e password robuste, non esponete la porta 3000 e aggiornate regolarmente i container:

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

Il database principale e i materiali salvati si trovano nel volume Docker data. Fermate i container prima di eseguire la copia:

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

Il nome karakeep_data presuppone che la directory del progetto sia /opt/karakeep; potete verificarlo con docker volume ls. L’indice di ricerca di Meilisearch può essere ricreato, ma per una libreria di grandi dimensioni è utile copiare anche il volume karakeep_meilisearch.

Inviate l’archivio da /var/backups/karakeep a un altro server, a un NAS o a uno storage a oggetti. Una copia sullo stesso VPS non protegge da un guasto del disco o dall’eliminazione della macchina virtuale.

Quale VPS scegliere per Karakeep

Per una libreria personale senza Ollama è adatto un VPS Linux con 2 vCPU, 2 GB di RAM e 20–30 GB di NVMe. Per una grande importazione, più utenti e l’archiviazione completa, scegliete 4 GB di RAM e un disco più capiente.

Karakeep può essere eseguito su un VPS di tropic.host: un IP permanente semplifica il collegamento del dominio, mentre lo storage NVMe è utile per SQLite, l’indice di ricerca e molti file di piccole dimensioni. Le risorse possono essere aumentate man mano che l’archivio cresce.

Calcolate separatamente le risorse per Ollama in locale: persino un piccolo modello linguistico può richiedere più memoria dell’intero stack principale di Karakeep.

Conclusione

Karakeep trasforma link sparsi in una libreria personale ricercabile. Salva pagine, note, immagini e PDF e supporta OCR, elenchi, estensioni, applicazioni mobili e l’etichettatura IA facoltativa.

Per iniziare sono sufficienti un piccolo VPS, Docker Compose, un dominio e HTTPS. Dopo l’installazione, chiudete le registrazioni, controllate l’uso del disco e conservate un backup esterno.

FAQ

Karakeep è gratuito?

La versione self-hosted è open source e non richiede un abbonamento obbligatorio. Si pagano il VPS, il dominio, lo spazio per i backup e, quando necessario, un’API IA esterna.

Serve una chiave API per usare Karakeep?

No. Il salvataggio e l’indicizzazione dei materiali, gli elenchi, le note, l’OCR e la ricerca full-text funzionano senza IA. Un modello è necessario per i tag automatici, i riepiloghi e le funzioni correlate.

Di quanta RAM ha bisogno Karakeep?

Un punto di partenza pratico per un utente senza Ollama è 2 GB di RAM. Per importazioni grandi, più utenti e un’elaborazione intensa, 4 GB sono più comodi.

Posso importare i preferiti dal browser o da Pocket?

Sì. Karakeep supporta il normale file HTML dei preferiti del browser, Pocket, Omnivore e diversi altri formati. Dopo l’importazione, Karakeep elabora le pagine e le aggiunge alla ricerca.

L’articolo resterà disponibile se il sito originale scompare?

Karakeep salva il testo estratto e uno screenshot e, quando è attiva l’archiviazione completa, anche una copia locale o un PDF. Le pagine protette da autenticazione e le applicazioni web complesse potrebbero essere salvate solo parzialmente.