Karakeep — Setup

AI-powered bookmark manager with auto-tagging, page archiving, and full-text search. Runs as a Docker Compose stack on a dedicated Debian LXC (117). OIDC via PocketID, AI via Ollama.

Infrastructure

Host	LXC ID	Internal	External	CPU	RAM	Disk
Debian LXC	117	192.168.1.217:3000	https://karakeep.eva-00.network	2 cores	2 GiB	8 GiB

Observability

Logs

Container logs are collected via Docker log driver. Query in Loki:

Query	Purpose
`{container_name="karakeep-karakeep-1"}`	Karakeep app logs
`{container_name="karakeep-meilisearch-1"}`	Search engine logs
`{container_name="karakeep-chrome-1"}`	Headless Chrome (archiving)
`{container_name=~"karakeep.*"} \\|= "error"`	All errors

Access: Grafana → Explore → Loki → Enter query

IaC

Artifact	Path
Playbook	`ansible/playbooks/karakeep.yml`
Workflow	`.forgejo/workflows/karakeep.yml`
Docker Compose	`services/karakeep/docker-compose.yml`
Caddy entry	`services/caddy/Caddyfile` → `karakeep.eva-00.network`
Glance entry	`services/glance/glance.yml` → Knowledge section

The playbook manages the full lifecycle:

Provisions LXC 117 on Proxmox (if not exists)
Installs Docker and sqlite3
Fetches secrets from Vault
Deploys Docker Compose stack (web app + Chrome + Meilisearch)
Creates admin user via tRPC signup endpoint
Generates API key via SQLite insert
Stores API key in Vault
Locks down signups and password auth
Enables OIDC auto-redirect

First-run setup guide: See karakeep-iac-setup.md for the full automation walkthrough.

Auth

Component	Details
OIDC Provider	PocketID (`auth.eva-00.network`)
Callback URL	`https://karakeep.eva-00.network/api/auth/callback/custom`
Auth mode	OIDC-only (password auth disabled after first-run)
Auto-redirect	Enabled — users go straight to PocketID

Secrets

Vault path: secret/data/karakeep

Key	Purpose
`admin_email`	Admin account email
`admin_password`	Admin account password (used for initial signup only)
`nextauth_secret`	JWT session signing key
`meili_master_key`	Meilisearch authentication key
`pocketid_client_id`	OIDC client ID
`pocketid_client_secret`	OIDC client secret
`api_key`	REST API key (`ak2_...` format, generated on first run)

AI Integration

Karakeep connects to the Ollama instance on LXC 107 for:

Auto-tagging: AI generates tags when bookmarks are saved
Summarization: AI summarizes article content
OCR: Vision model extracts text from images

Setting	Value
`OLLAMA_BASE_URL`	`http://192.168.1.107:11434`
`INFERENCE_TEXT_MODEL`	`llama3.1`
`INFERENCE_IMAGE_MODEL`	`llava`

Containers

Container	Image	Purpose
`karakeep-karakeep-1`	`ghcr.io/karakeep-app/karakeep:release`	Web app + API
`karakeep-chrome-1`	`gcr.io/zenika-hub/alpine-chrome:124`	Headless Chrome for page archiving
`karakeep-meilisearch-1`	`getmeili/meilisearch:v1.37.0`	Full-text search engine

Volumes

Volume	Mount	Purpose
`karakeep_data`	`/data`	SQLite DB, archived pages, uploaded assets
`karakeep_meilisearch`	`/meili_data`	Search index

Client Apps

Platform	App	Notes
iOS/iPadOS	Karakeep App (official)	Share sheet extension for saving from Safari
macOS Safari	Karakeeper (third-party)	Native Safari extension, one-tap bookmarking
Chrome/Firefox	Karakeep Extension	Browser extension
Any	REST API / iOS Shortcuts	`POST /api/v1/bookmarks` with Bearer token

MCP Server

Karakeep has an official first-party MCP server for AI integration:

npm: @karakeep/mcp
Docker: ghcr.io/karakeep-app/karakeep-mcp:latest
Docs: https://docs.karakeep.app/integrations/mcp/