Karakeep na VPS: własne archiwum zakładek z wyszukiwaniem i AI

6.09.20267 min czytania

Tropic

Karakeep na VPS: własne archiwum zakładek z wyszukiwaniem i AI

Language: pl

Karakeep: instalacja osobistego archiwum zakładek na VPS

Zapisanie linku jest łatwe. Znalezienie go sześć miesięcy później bywa trudniejsze — zwłaszcza gdy strona się zmieniła, zniknęła albo zginęła wśród setek zakładek.

Karakeep przechowuje nie tylko URL, lecz także treść strony, podgląd, notatki, obrazy i pliki PDF. Archiwum można przeszukiwać tekstowo, porządkować elementy na listach i automatycznie oznaczać je tagami za pomocą AI. Aplikacja działa na własnym VPS, a podłączenie modelu językowego jest opcjonalne.

Poniżej omawiamy możliwości Karakeep, wymagania serwera oraz instalację na Ubuntu 24.04 z Docker Compose, HTTPS i kopiami zapasowymi.

Karakeep w siedmiu krokach

Utwórz Linux VPS i skieruj do niego subdomenę, na przykład keep.example.com.
Zainstaluj Docker Engine i Docker Compose.
Pobierz oficjalny plik docker-compose.yml.
Wygeneruj sekrety i uruchom Karakeep, Chrome oraz Meilisearch.
Zamknij wewnętrzny port 3000 i włącz HTTPS przez Caddy.
Utwórz pierwsze konto, a następnie wyłącz otwartą rejestrację.
Zainstaluj rozszerzenie przeglądarki lub aplikację mobilną i zaimportuj zakładki.

Klucz AI nie jest potrzebny do uruchomienia usługi. Bez niego nadal będą działać zapisywanie stron, listy, notatki, OCR i wyszukiwanie pełnotekstowe. Automatyczne tagi i podsumowania nie będą jednak generowane.

Czym jest Karakeep

Karakeep to otwartoźródłowa, samodzielnie hostowana aplikacja do przechowywania linków, notatek tekstowych, obrazów i plików PDF w jednej bibliotece. Wcześniej projekt nosił nazwę Hoarder.

Nazwa pochodzi od arabskiego słowa karakeeb, określającego rozrzucone rzeczy, które wyglądają jak bałagan, ale mogą mieć ukrytą wartość. Dobrze opisuje to typową kolekcję zakładek: przydatnych materiałów jest dużo, lecz znalezienie właściwego bywa trudne.

Po dodaniu linku Karakeep pobiera jego tytuł i opis, wyodrębnia czytelny tekst, tworzy podgląd i w razie potrzeby może zapisać lokalną kopię strony.

Funkcja	Zakładki przeglądarki	Karakeep
Co jest przechowywane	URL i tytuł	Tekst, podgląd, notatki i załączniki
Wyszukiwanie	Po tytule i adresie	Po treści, tagach i notatkach
Gdy strona zniknie	Pozostaje niedziałający URL	Pozostaje tekst, zrzut ekranu lub pełne archiwum
Organizacja	Foldery	Tagi, listy ręczne i inteligentne
Dostęp	W przeglądarce	WWW, rozszerzenia, iOS i Android
Serwer	Profil przeglądarki lub jego usługa w chmurze	Twój VPS lub serwer domowy

Główne funkcje Karakeep

Linki, notatki, obrazy i pliki PDF

Każdy element może być linkiem, notatką tekstową albo przesłanym plikiem. OCR wyodrębnia tekst z obrazów i plików PDF, dzięki czemu one również stają się przeszukiwalne. Do elementu można dołączyć notatkę, cytat lub dodatkowy plik.

Wyszukiwanie treści

Meilisearch indeksuje zapisany tekst, notatki i metadane. Nie trzeba pamiętać dokładnego tytułu — wystarczy fraza lub temat. Po skonfigurowaniu embeddingów dostępne jest również wyszukiwanie semantyczne według znaczenia.

Listy inteligentne i współdzielone

Jeden element może należeć jednocześnie do kilku list, bez tworzenia duplikatów. Lista może pozostać prywatna, być udostępniona za pomocą linku albo wspólnie edytowana przez innych użytkowników.

Lista inteligentna to zapisane zapytanie wyszukiwania, które aktualizuje się automatycznie. Może na przykład wyświetlać wszystkie elementy oznaczone tagiem ai, dodane w ciągu ostatniego tygodnia.

Archiwizowanie stron

Domyślnie Karakeep zapisuje wyodrębniony tekst i zrzut ekranu widocznej części strony. Można dodatkowo włączyć zrzut całej strony, plik PDF albo samodzielne archiwum HTML. Chroni to bibliotekę przed niedziałającymi linkami, ale zwiększa zużycie dysku.

Strony wymagające uwierzytelnienia, zaawansowanej ochrony przed botami oraz interaktywne aplikacje mogą nie zostać zapisane w całości. Ważne materiały lepiej przesłać osobno jako plik PDF lub inny plik.

Opcjonalne tagowanie AI

Karakeep może generować tagi i krótkie podsumowania za pomocą zewnętrznego API zgodnego z OpenAI albo lokalnego modelu Ollama. Bez AI aplikacja nadal jest w pełni funkcjonalnym menedżerem zakładek.

Lokalny model nie wysyła materiałów do zewnętrznego dostawcy, ale wymaga znacznie więcej pamięci RAM. Dlatego Ollama często jest uruchamiana osobno, poza główną instancją Karakeep.

Wymagania serwera dla Karakeep

Oficjalna dokumentacja nie określa stałych minimalnych wymagań CPU i RAM. Kompletna instalacja obejmuje trzy kontenery:

Karakeep przechowuje bazę danych i udostępnia interfejs;
headless Chrome otwiera strony, uruchamia JavaScript i wykonuje zrzuty ekranu;
Meilisearch indeksuje bibliotekę.

Praktyczna konfiguracja dla jednego użytkownika bez lokalnego LLM to:

2 vCPU;
2 GB RAM;
20–30 GB SSD lub NVMe;
Ubuntu 24.04 LTS;
publiczny adres IP i domena.

Dla kilku użytkowników, dużego importu, wielu kanałów RSS i plików PDF wygodniejsze będzie 4 GB RAM. Wymagania dotyczące dysku zależą od trybu archiwizacji: tekst zajmuje niewiele miejsca, natomiast pełne zrzuty ekranu, pliki PDF i filmy mogą szybko powiększyć bibliotekę.

Jak zainstalować Karakeep na VPS

Przykład korzysta z Ubuntu 24.04 i subdomeny keep.example.com.

1. Skonfiguruj DNS i zaporę

Utwórz rekord DNS A wskazujący na adres IP serwera, a następnie połącz się przez SSH:

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

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

Nie zamykaj bieżącej sesji SSH, dopóki nie sprawdzisz, że nowe połączenie działa.

2. Zainstaluj 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. Pobierz konfigurację 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

Wygeneruj dwa różne sekrety:

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

Utwórz /opt/karakeep/.env:

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

Nie publikuj .env: pierwszy sekret podpisuje tokeny uwierzytelniania, a drugi chroni Meilisearch.

4. Zamknij wewnętrzny port

W docker-compose.yml zamień:

ports:
  - 3000:3000

na:

ports:
  - 127.0.0.1:3000:3000

Dzięki temu port 3000 nie będzie bezpośrednio dostępny z internetu.

5. Uruchom kontenery

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

Usługi web, chrome i meilisearch powinny działać. Logi wyświetlisz poleceniem:

docker compose logs --tail=200

6. Włącz 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

Jeśli DNS jest skonfigurowany, a porty 80 i 443 otwarte, Caddy automatycznie pobierze certyfikat TLS. Następnie otwórz https://keep.example.com.

7. Utwórz administratora i zamknij rejestrację

Pierwszy zarejestrowany użytkownik automatycznie zostaje administratorem. Po utworzeniu konta ustaw w .env:

DISABLE_SIGNUPS=true

Zastosuj zmianę:

cd /opt/karakeep
docker compose up -d

Administrator nadal będzie mógł tworzyć inne konta ręcznie.

Import danych, rozszerzenia i aplikacje mobilne

Karakeep oferuje rozszerzenia dla Chrome, Firefoksa i Safari oraz aplikacje na iOS i Androida. Na telefonie link można wysłać do archiwum z poziomu systemowego menu Udostępnij.

Istniejące zakładki można zaimportować ze standardowego pliku HTML przeglądarki, Pocket, Omnivore i innych obsługiwanych usług. Duże archiwum lepiej dodawać partiami: serwer musi otworzyć strony, wyodrębnić tekst, utworzyć zrzuty ekranu i zbudować indeks wyszukiwania.

Jak włączyć AI i archiwizowanie całych stron

W przypadku OpenAI dodaj do .env:

OPENAI_API_KEY=YOUR_API_KEY

Inna usługa zgodna z OpenAI może dodatkowo wymagać OPENAI_BASE_URL. Aby użyć lokalnego modelu, ustaw OLLAMA_BASE_URL z adresem dostępnym z kontenera.

Pełną lokalną kopię strony włącz osobno:

CRAWLER_FULL_PAGE_ARCHIVE=true

Dostępne są również opcje CRAWLER_FULL_PAGE_SCREENSHOT=true i CRAWLER_STORE_PDF=true. Nie włączaj wszystkich trybów bez potrzeby — wyraźnie zwiększają zużycie dysku. Po zmianie .env uruchom docker compose up -d.

Bezpieczeństwo, aktualizacje i kopie zapasowe

Crawler Karakeep otwiera zapisane przez użytkowników adresy z sieci serwera. Dlatego nie pozostawiaj otwartej rejestracji i przyznawaj dostęp wyłącznie zaufanym osobom. Podstawowa ochrona SSRF jest obecna, ale w przypadku publicznej usługi oficjalny projekt zaleca odizolowanie przeglądarki albo kierowanie jej przez ograniczony proxy.

Korzystaj także z HTTPS, silnych haseł, nie wystawiaj portu 3000 i regularnie aktualizuj kontenery:

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

Główna baza danych i zapisane materiały znajdują się w wolumenie Dockera o nazwie data. Przed jego skopiowaniem zatrzymaj kontenery:

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

Nazwa karakeep_data zakłada, że katalog projektu to /opt/karakeep; możesz ją sprawdzić poleceniem docker volume ls. Indeks Meilisearch można odbudować, ale przy dużej bibliotece warto również wykonać kopię wolumenu karakeep_meilisearch.

Prześlij archiwum z /var/backups/karakeep na inny serwer, NAS albo do magazynu obiektowego. Kopia na tym samym VPS nie chroni przed awarią dysku ani usunięciem maszyny wirtualnej.

Jaki VPS wybrać dla Karakeep

Do osobistej biblioteki bez Ollama wystarczy Linux VPS z 2 vCPU, 2 GB RAM i 20–30 GB NVMe. Przy dużym imporcie, kilku użytkownikach i pełnej archiwizacji wybierz 4 GB RAM oraz większy dysk.

Karakeep można uruchomić na VPS od tropic.host: stały adres IP ułatwia konfigurację domeny, a pamięć NVMe sprawdza się przy SQLite, indeksie wyszukiwania i wielu małych plikach. Zasoby można zwiększać wraz z rozwojem archiwum.

Zasoby dla lokalnego Ollama zaplanuj osobno: nawet niewielki model językowy może wymagać więcej pamięci niż cały główny stos Karakeep.

Podsumowanie

Karakeep zamienia rozproszone linki w osobistą, przeszukiwalną bibliotekę. Zapisuje strony, notatki, obrazy i pliki PDF oraz obsługuje OCR, listy, rozszerzenia, aplikacje mobilne i opcjonalne tagowanie AI.

Do rozpoczęcia pracy wystarczą niewielki VPS, Docker Compose, domena i HTTPS. Po instalacji zamknij rejestrację, kontroluj zużycie dysku i utrzymuj zewnętrzną kopię zapasową.

FAQ

Czy Karakeep jest darmowy?

Wersja samodzielnie hostowana jest otwartoźródłowa i nie wymaga obowiązkowej subskrypcji. Płacisz za VPS, domenę, miejsce na kopie zapasowe oraz — jeśli jest potrzebne — zewnętrzne API AI.

Czy do działania Karakeep potrzebny jest klucz API?

Nie. Zapisywanie i indeksowanie materiałów, listy, notatki, OCR oraz wyszukiwanie pełnotekstowe działają bez AI. Model jest potrzebny do automatycznych tagów, podsumowań i powiązanych funkcji.

Ile RAM potrzebuje Karakeep?

Praktyczny punkt wyjścia dla jednego użytkownika bez Ollama to 2 GB RAM. Przy dużych importach, kilku użytkownikach i intensywnym przetwarzaniu wygodniejsze będzie 4 GB.

Czy mogę importować zakładki z przeglądarki lub Pocket?

Tak. Karakeep obsługuje standardowy plik HTML z zakładkami przeglądarki, Pocket, Omnivore i kilka innych formatów. Po imporcie Karakeep przetwarza strony i dodaje je do wyszukiwania.

Czy artykuł pozostanie dostępny, jeśli oryginalna strona zniknie?

Karakeep przechowuje wyodrębniony tekst i zrzut ekranu, a po włączeniu pełnej archiwizacji również lokalną kopię lub plik PDF. Strony wymagające uwierzytelnienia i złożone aplikacje internetowe mogą zostać zapisane tylko częściowo.

Powrót do bloga