Karakeep – mit Docker Compose und Traefik installieren

Speichere schnell Links, Notizen und Bilder, und karakeep versieht sie automatisch mit Tags, um sie mithilfe von KI schneller wiederzufinden. Entwickelt für alle, die gerne Daten sammeln!

Ich zeige dir hier, wie ich von Obsidian zu karakeep wechselte, was den Vorteil eines zentralen Servers mit sich brachte. Bei Obsidian musste ich die App überall lokal installieren und dann die Notizen über Nextcloud synchronisieren. Zudem ist karakeep darauf spezialisiert, ganze Webseiten zu speichern.

1. Grundvoraussetzungen

• Docker und Docker Compose und Debian/Ubuntu
• Traefik V3 Installation, Konfiguration und CrowdSec-Security

2. Ordner anlegen

Im ersten Schritt legen wir uns ein Verzeichnis an und wählen dieses aus.

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

3. Docker Compose erstellen

Nun erstellen wir uns eine Docker Compose Datei, indem wir diese von der karakeep-Github-Seite herunterladen.

wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

Es müssen für Traefik (und Crowdsec) diverse neue Einträge gemacht werden, die ich direkt in der Datei mit Kommentaren versehen habe.

Die ganze Docker Compose Datei sieht dann bei mir wie folgt aus:

services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    restart: unless-stopped
    volumes:
      # By default, the data is stored in a docker volume called "data".
      # If you want to mount a custom directory, change the volume mapping to:
      - /daten-server/karakeep:/data ## <- Hier musst du den Pfad für den Speicherort sämtlicher Daten angeben (achte auf genügend Platz!)
      #- data:/data
    ports:
      - 3000:3000
    env_file:
      - .env
    environment:
      MEILI_ADDR: http://meilisearch:7700
      BROWSER_WEB_URL: http://chrome:9222
      # OPENAI_API_KEY: ...
      OLLAMA_BASE_URL: http://192.168.1.22:11434 # <- Hier folgen die Angaben für die KI (vgl. unten, richtig IP angeben!)
      INFERENCE_TEXT_MODEL: gemma3:27b # <- Modell angeben gemäss deiner Installation von Ollama
      INFERENCE_IMAGE_MODEL: llava # <- Modell angeben gemäss deiner Installation von Ollama
      INFERENCE_CONTEXT_LENGTH: 4096 # <- hier doppelte Grösse, wäre vielleicht auch noch mehr möglich, je nach Leistung deines Setups
      
      # You almost never want to change the value of the DATA_DIR variable.
      # If you want to mount a custom directory, change the volume mapping above instead.
      DATA_DIR: /data # DON'T CHANGE THIS
    labels: # <- der ganze Abschnitt "labels" muss für Traefik und Crowdsec eingefügt werden (ersetze die Domain mit deiner Domain
      traefik.docker.network: proxy
      traefik.enable: "true"
      traefik.http.routers.karakeep.entrypoints: websecure
      traefik.http.routers.karakeep.middlewares: default@file
      traefik.http.routers.karakeep.rule: Host(`karakeep.beispiel.de`)
      traefik.http.routers.karakeep.service: karakeep
      traefik.http.routers.karakeep.tls: "true"
      traefik.http.routers.karakeep.tls.certresolver: http_resolver
      traefik.http.services.karakeep.loadbalancer.server.port: "3000"
    networks: # <- auch dieser ganze Abschnitt "networks" ist für Traefik nötig und muss eingefügt werden
      default: null
      proxy: null

  chrome:
    image: gcr.io/zenika-hub/alpine-chrome:124
    restart: unless-stopped
    command:
      - --no-sandbox
      - --disable-gpu
      - --disable-dev-shm-usage
      - --remote-debugging-address=0.0.0.0
      - --remote-debugging-port=9222
      - --hide-scrollbars
    networks:
      default: null

  meilisearch:
    image: getmeili/meilisearch:v1.13.3
    restart: unless-stopped
    env_file:
      - .env
    environment:
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - meilisearch:/meili_data
    networks:
      default: null

volumes:
  meilisearch:
  data:
  
networks: # <- und schliesslich auch dieser ganze Abschnitt ist für Traefik nötig und muss eingefügt werden (achte auf die korrekte Einrückung!)
  proxy:
    external: true

3. Festlegen der Umgebungsvariablen

Um die App zu konfigurieren, erstelle eine .env-Datei im Verzeichnis

nano .env

und füge diese minimalen Umgebungsvariablen hinzu:

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=super_random_string # <- anpassen
MEILI_MASTER_KEY=another_random_string # <- anpassen
NEXTAUTH_URL=https://karakeep.beispiel.de # <- anpassen

Du solltest die zufälligen Zeichenfolgen ändern. Du kannst openssl rand -base64 36 in einem separaten Terminalfenster verwenden, um die zufälligen Zeichenfolgen zu generieren. Du solltest auch die Variable NEXTAUTH_URL ändern, damit sie auf deine Serveradresse verweist.

Mit KARAKEEP_VERSION=release wird die neueste stabile Version abgerufen. Möglicherweise möchtest du stattdessen die Version festlegen, um die Upgrades zu steuern (z. B. KARAKEEP_VERSION=0.10.0). Die neuesten Versionen findest du hier.

Der persistente Speicher und die Verknüpfung zwischen den verschiedenen Diensten sind bereits in der Docker-Compose-Datei berücksichtigt.

Beachte, dass du jedes Mal, wenn du die Datei .env änderst, docker compose up erneut ausführen musst.

Wenn du weitere Konfigurationsparameter wünschst, lese die Konfigurationsdokumentation hier.

4. KI (OpenAI oder Ollama) einrichten

Um die automatische Tagging-Funktion zu aktivieren, musst du OpenAI oder Ollama konfigurieren. Dies ist optional, wird jedoch dringend empfohlen.

4.1 Open AI

• Befolge die Anweisungen in der OpenAI-Hilfe, um einen API-Schlüssel zu erhalten.
• Füge den OpenAI-API-Schlüssel zur env-Datei hinzu:

OPENAI_API_KEY=<Schlüssel>

Weitere Informationen zu den Kosten für die Nutzung von OpenAI finden Sie hier.

4.2 Ollama

Wenn du stattdessen Ollama (https://ollama.com/) für lokale Inferenz verwenden möchtest, musst du dieses zuerst installieren. Ich habe bei mir Ollama auf einem sepraten Server im LAN installiert und dessen IP:Port oben in der Docker Compose Datei schon hinterlegt.

Hinweis: Die Qualität der Tags, die du erhältst, hängt von der Qualität des von dir gewählten Modells ab.

• Stelle sicher, dass Ollama ausgeführt wird.
• Setze die OLLAMA_BASE_URL env-Variable auf die Adresse der Ollama-API.
• Setze INFERENCE_TEXT_MODEL auf das Modell, das du für die Textinferenz in Ollama verwenden möchtest (zum Beispiel: llama3.1)
• Setze INFERENCE_IMAGE_MODEL auf das Modell, das du für die Bildinferenz in Ollama verwenden möchtest (zum Beispiel: llava)
• Stelle sicher, dass du die Modelle, die du verwenden möchtest, mit ollama pull abgerufen hast.
• Möglicherweise möchtest du die INFERENCE_CONTEXT_LENGTH anpassen, da der Standardwert recht klein ist. Je grösser der Wert, desto besser die Qualität der Tags, aber desto “teurer” wird die Inferenz bzw. desto länger arbeitet deine Ollama-Instanz.

5. Container starten

Dazu gibst du einfach folgenden Befehl ein:

docker compose -f /opt/containers/karakeep/docker-compose.yml up -d

Dann kannst du https://karakeep.beispiel.de aufrufen. Du solltest nun auf der Anmeldeseite begrüsst werden.

Dort dann einen ersten User registrieren, der damit auch gleich zum Administrator wird.

6. Bemerkungen

6.1 Import von Obsidian

Die einzelnen “Notizen” sind ja im Vault als Textdateien mit der Endung *.md abgelegt. Zum Import bin ich so vorgegangen:

• Zuerst musst du wie Ordner-Struktur von Obsidian in Karakeep nachbilden.
• Dann kannst du alle Notizen aus einem Ordner von Obision direkt in die Oberfläche von karakeep ziehen und so importieren (auf die Fläche mit “Neuer Eintrag” ziehen)
• Falls du in der Notiz noch etwas ergänzen oder ändern möchtest, muss du dann bei den drei Punkten in der Kachel auf “Editor öffnen” klicken…

6.2 Whitelist für Crowdsec einrichten

Auf meinem Server produzierte Karakeep bei gewissen Aktionen (z.B. Umstellung von Dark Mode auf Light Mode) oder beim Bearbeiten von Einträgen einen Ban in Crowdsec mit dem Grund “crowdsecurity/http-crawl-non_statics”. Dadurch wurde der Zugang zum Server geblockt und ich musste ihn über einen anderen Zugang mit

docker exec crowdsec cscli decisions list
docker exec crowdsec cscli decisions delete --ip x.x.x.x 

wieder möglich machen. Um dies zu umgehen, habe ich analog zur Anleitung unter https://goneuland.de/crowdsec-whitelist-fuer-eine-ip-erstellen folgende Whitelist für Corwdsec erstellt:

sudo nano /opt/containers/traefik-crowdsec-stack/data/crowdsec/config/parsers/s02-enrich/karakeep-whitelist.yaml

und folgenden Inhalt eingegeben:

name: me/karakeep-whitelist
description: "Whitelist events from karaakeep"
whitelist:
  reason: "Karakeep Whitelist"
  expression:
   - evt.Meta.http_status == '200' && evt.Meta.http_verb in ['PROPFIND', 'GET'] && evt.Meta.http_path matches '^/dashboard/'

Dann noch den Traefik-Crowdscec-Stack neu starten…

cd /opt/containers/traefik-crowdsec-stack/
docker compose up -d --force-recreate

und seit dann habe ich diese Probleme nicht mehr (crossing fingers!).