homelab/compose/services/karakeep

Karakeep - Bookmark Everything App

AI-powered bookmark manager for links, notes, images, and PDFs with automatic tagging and full-text search.

Overview

Karakeep (previously known as Hoarder) is a self-hostable bookmark-everything app:

• ✅ Bookmark Everything: Links, notes, images, PDFs
• ✅ AI-Powered: Automatic tagging and summarization
• ✅ Full-Text Search: Find anything instantly with Meilisearch
• ✅ Web Archiving: Save complete webpages (full page archive)
• ✅ Browser Extensions: Chrome and Firefox support
• ✅ Mobile Apps: iOS and Android apps available
• ✅ Ollama Support: Use local AI models (no cloud required!)
• ✅ OCR: Extract text from images
• ✅ Self-Hosted: Full control of your data

Quick Start

1. Configure Secrets

cd ~/homelab/compose/services/karakeep

# Edit .env and update:
# - NEXTAUTH_SECRET (generate with: openssl rand -base64 36)
# - MEILI_MASTER_KEY (generate with: openssl rand -base64 36)
nano .env

2. Deploy

docker compose up -d

3. Access

Go to: https://links.fig.systems

First-time setup:

1. Create your admin account
2. Start bookmarking!

Features

Bookmark Types

1. Web Links

• Save any URL
• Automatic screenshot capture
• Full webpage archiving
• Extract title, description, favicon
• AI-generated summary and tags

2. Notes

• Quick text notes
• Markdown support
• AI-powered categorization
• Full-text searchable

3. Images

• Upload images directly
• OCR text extraction (if enabled)
• AI-based tagging
• Image search

4. PDFs

• Upload PDF documents
• Full-text indexing
• Searchable content

AI Features

Karakeep can use AI to automatically:

• Tag your bookmarks
• Summarize web content
• Extract key information
• Organize by category

Three AI options:

1. Ollama (Recommended - Local & Free)

# In .env, uncomment:
OLLAMA_BASE_URL=http://ollama:11434
INFERENCE_TEXT_MODEL=llama3.2:3b
INFERENCE_IMAGE_MODEL=llava:7b

2. OpenAI

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
INFERENCE_TEXT_MODEL=gpt-4o-mini

3. OpenRouter (multiple providers)

OPENAI_API_KEY=sk-or-v1-...
OPENAI_BASE_URL=https://openrouter.ai/api/v1
INFERENCE_TEXT_MODEL=anthropic/claude-3.5-sonnet

Web Archiving

Karakeep saves complete web pages for offline viewing:

• Full HTML archive
• Screenshots of the page
• Extracted text for search
• Works offline - view archived pages anytime

Search

Powered by Meilisearch:

• Instant full-text search
• Fuzzy matching - finds similar terms
• Filter by type, tags, dates
• Search across titles, content, tags, notes

Browser Extensions

Install extensions:

• Chrome Web Store
• Firefox Add-ons

Configure extension:

1. Install extension
2. Click extension icon
3. Enter server URL: https://links.fig.systems
4. Login with your credentials
5. Save bookmarks from any page!

Mobile Apps

Download apps:

• iOS App Store
• Android Google Play

Setup:

1. Install app
2. Open app
3. Enter server: https://links.fig.systems
4. Login
5. Bookmark on the go!

Configuration

Basic Settings

Disable public signups:

DISABLE_SIGNUPS=true

Set max file size (100MB default):

MAX_ASSET_SIZE_MB=100

Enable OCR for multiple languages:

OCR_LANGS=eng,spa,fra,deu

Ollama Integration

Prerequisites:

1. Deploy Ollama service (see compose/services/ollama/)
2. Pull models: docker exec ollama ollama pull llama3.2:3b

Enable in Karakeep:

# In karakeep/.env
OLLAMA_BASE_URL=http://ollama:11434
INFERENCE_TEXT_MODEL=llama3.2:3b
INFERENCE_IMAGE_MODEL=llava:7b
INFERENCE_LANG=en

Restart:

docker compose restart

Recommended models:

• Text: llama3.2:3b (fast, good quality)
• Images: llava:7b (vision model)
• Advanced: llama3.3:70b (slower, better results)

Advanced Settings

Custom logging:

LOG_LEVEL=debug  # Options: debug, info, warn, error

Custom data directory:

DATADIR=/custom/path

Chrome timeout (for slow sites):

# Add to compose.yaml environment section
BROWSER_TIMEOUT=60000  # 60 seconds

Usage Workflows

1. Bookmark a Website

Via Browser:

1. Click Karakeep extension
2. Bookmark opens automatically
3. AI generates tags and summary
4. Edit tags/notes if needed
5. Save

Via Mobile:

1. Open share menu
2. Select Karakeep
3. Bookmark saved

Manually:

1. Open Karakeep
2. Click "+" button
3. Paste URL
4. Click Save

2. Quick Note

1. Open Karakeep
2. Click "+" → "Note"
3. Type your note
4. AI auto-tags
5. Save

3. Upload Image

1. Click "+" → "Image"
2. Upload image file
3. OCR extracts text (if enabled)
4. AI generates tags
5. Save

4. Search Everything

Simple search:

• Type in search box
• Results appear instantly

Advanced search:

• Filter by type (links, notes, images)
• Filter by tags
• Filter by date range
• Sort by relevance or date

5. Organize with Tags

Auto-tags:

• AI generates tags automatically
• Based on content analysis
• Can be edited/removed

Manual tags:

• Add your own tags
• Create tag hierarchies
• Color-code tags

Tag management:

• Rename tags globally
• Merge duplicate tags
• Delete unused tags

Browser Extension Usage

Quick Bookmark

1. Visit any page
2. Click extension icon (or keyboard shortcut)
3. Automatically saved with:
   • URL
   • Title
   • Screenshot
   • Full page archive
   • AI tags and summary

Save Selection

1. Highlight text on any page
2. Right-click → "Save to Karakeep"
3. Saves as note with source URL

Save Image

1. Right-click image
2. Select "Save to Karakeep"
3. Image uploaded with AI tags

Mobile App Features

• Share from any app to Karakeep
• Quick capture - bookmark in seconds
• Offline access to archived content
• Search your entire collection
• Browse by tags
• Dark mode support

Data Management

Backup

Important data locations:

compose/services/karakeep/
├── data/           # Uploaded files, archives
└── meili_data/     # Search index

Backup script:

#!/bin/bash
cd ~/homelab/compose/services/karakeep
tar czf karakeep-backup-$(date +%Y%m%d).tar.gz ./data ./meili_data

Export

Export bookmarks:

1. Settings → Export
2. Choose format:
   • JSON (complete data)
   • HTML (browser-compatible)
   • CSV (spreadsheet)
3. Download

Import

Import from other services:

1. Settings → Import
2. Select source:
   • Browser bookmarks (HTML)
   • Pocket
   • Raindrop.io
   • Omnivore
   • Instapaper
3. Upload file
4. Karakeep processes and imports

Troubleshooting

Karakeep won't start

Check logs:

docker logs karakeep
docker logs karakeep-chrome
docker logs karakeep-meilisearch

Common issues:

• Missing NEXTAUTH_SECRET in .env
• Missing MEILI_MASTER_KEY in .env
• Services not on karakeep_internal network

Bookmarks not saving

Check chrome service:

docker logs karakeep-chrome

Verify chrome is accessible:

docker exec karakeep curl http://karakeep-chrome:9222

Increase timeout:

# Add to .env
BROWSER_TIMEOUT=60000

Search not working

Rebuild search index:

# Stop services
docker compose down

# Remove search data
rm -rf ./meili_data

# Restart (index rebuilds automatically)
docker compose up -d

Check Meilisearch:

docker logs karakeep-meilisearch

AI features not working

With Ollama:

# Verify Ollama is running
docker ps | grep ollama

# Test Ollama connection
docker exec karakeep curl http://ollama:11434

# Check models are pulled
docker exec ollama ollama list

With OpenAI/OpenRouter:

• Verify API key is correct
• Check API balance/credits
• Review logs for error messages

Extension can't connect

Verify server URL:

• Must be https://links.fig.systems
• Not http:// or localhost

Check CORS:

# Add to .env if needed
CORS_ALLOW_ORIGINS=https://links.fig.systems

Clear extension data:

1. Extension settings
2. Logout
3. Clear extension storage
4. Login again

Mobile app issues

Can't connect:

• Use full HTTPS URL
• Ensure server is accessible externally
• Check firewall rules

Slow performance:

• Check network speed
• Reduce image quality in app settings
• Enable "Low data mode"

Performance Optimization

For Large Collections (10,000+ bookmarks)

Increase Meilisearch RAM:

# In compose.yaml, add to karakeep-meilisearch:
deploy:
  resources:
    limits:
      memory: 2G
    reservations:
      memory: 1G

Optimize search index:

# In .env
MEILI_MAX_INDEXING_MEMORY=1048576000  # 1GB

For Slow Archiving

Increase Chrome resources:

# In compose.yaml, add to karakeep-chrome:
deploy:
  resources:
    limits:
      memory: 1G
      cpus: '1.0'

Adjust timeouts:

BROWSER_TIMEOUT=90000  # 90 seconds

Database Maintenance

Vacuum (compact) database:

# Karakeep uses SQLite by default
docker exec karakeep sqlite3 /data/karakeep.db "VACUUM;"

Comparison with Linkwarden

Feature	Karakeep	Linkwarden
Bookmark Types	Links, Notes, Images, PDFs	Links only
AI Tagging	Yes (Ollama/OpenAI)	No
Web Archiving	Full page + Screenshot	Screenshot only
Search	Meilisearch (fuzzy)	Meilisearch
Browser Extension	Yes	Yes
Mobile Apps	iOS + Android	No official apps
OCR	Yes	No
Collaboration	Personal focus	Team features
Database	SQLite	PostgreSQL

Why Karakeep?

• More bookmark types
• AI-powered organization
• Better mobile support
• Lighter resource usage (SQLite vs PostgreSQL)
• Active development

Resources

• Official Website
• Documentation
• GitHub Repository
• Demo Instance
• Chrome Extension
• Firefox Extension

Next Steps

1. ✅ Deploy Karakeep
2. ✅ Create admin account
3. ✅ Install browser extension
4. ✅ Install mobile app
5. ⬜ Deploy Ollama for AI features
6. ⬜ Import existing bookmarks
7. ⬜ Configure AI models
8. ⬜ Set up automated backups

---

Bookmark everything, find anything! 🔖