# 03-karakeep.md

kstack:
  book: Centerpoint Home Lab
  chapter: Documents & Organization
  page: Karakeep
  tags: [karakeep, bookmarks, read-later, productivity]
---

## Overview

Karakeep is a self-hosted bookmark manager and read-it-later service. It crawls
saved URLs for their full text and screenshots, indexes them via Meilisearch,
and supports OCR on images (`ocr_langs=eng`). Video download is enabled
(yt-dlp backend, no size limit). SMTP is configured for email-to-save via Gmail.
New signups are disabled — account management is manual.

## Access

| Type     | URL                                        | Auth                        |
|----------|--------------------------------------------|-----------------------------|
| External | `https://bookmark.jeevesconsults.ca`       | GeoBlock + CrowdSec (own auth) |

External-only — no internal `home.local` route configured.

## Configuration

**Image:** `ghcr.io/karakeep-app/karakeep:latest`

### Key Environment Variables

| Variable                              | Value / Notes                                  |
|---------------------------------------|------------------------------------------------|
| `NEXTAUTH_URL`                        | `https://bookmark.jeevesconsults.ca`           |
| `NEXTAUTH_URL_INTERNAL`               | `http://karakeep-web:3000`                     |
| `NEXTAUTH_TRUST_HOST`                 | `true`                                         |
| `NEXTAUTH_SECRET`                     | **REDACTED**                                   |
| `DATA_DIR`                            | `/data`                                        |
| `ASSETS_DIR`                          | `/assets`                                      |
| `MEILI_ADDR`                          | `http://meilisearch:7700`                      |
| `MEILI_MASTER_KEY`                    | **REDACTED**                                   |
| `BROWSER_WEB_URL`                     | `http://chrome:9222` (headless Chromium)       |
| `OCR_LANGS`                           | `eng`                                          |
| `OCR_CONFIDENCE_THRESHOLD`            | `75`                                           |
| `CRAWLER_VIDEO_DOWNLOAD`              | `true`                                         |
| `CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE`     | `-1` (unlimited)                               |
| `CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC`  | `7200`                                         |
| `INFERENCE_ENABLE_AUTO_SUMMARIZATION` | `true`                                         |
| `MAX_ASSET_SIZE_MB`                   | `50`                                           |
| `DISABLE_SIGNUPS`                     | `true`                                         |
| `EMAIL_VERIFICATION_REQUIRED`         | `false`                                        |
| `SMTP_HOST`                           | `smtp.gmail.com`                               |
| `SMTP_PORT`                           | `587`                                          |
| `SMTP_SECURE`                         | `true`                                         |
| `SMTP_USER`                           | `jeeves5454@gmail.com`                         |
| `SMTP_FROM`                           | `jeeves5454@gmail.com`                         |
| `SMTP_PASSWORD`                       | **REDACTED**                                   |

### Traefik Labels

```yaml
traefik.http.routers.karakeep.rule: Host(`bookmark.jeevesconsults.ca`)
traefik.http.routers.karakeep.entrypoints: websecure
traefik.http.routers.karakeep.tls.certresolver: letsencrypt
traefik.http.routers.karakeep.middlewares: plex-geoblock@file,crowdsec-bouncer@file,karakeep-headers
traefik.http.middlewares.karakeep-headers.headers.customrequestheaders.X-Forwarded-Proto: https
traefik.http.services.karakeep.loadbalancer.server.port: 3000
```

## Volumes / Bind Mounts

| Host Path                             | Container Path | Purpose               |
|---------------------------------------|----------------|-----------------------|
| `/home/jeeves/docker/karakeep/data`   | `/data`        | Database and app data |
| `/mnt/data/karakeep`                  | `/assets`      | Saved assets (screenshots, videos) |

## Stack Companions

Karakeep requires additional sidecar containers (Meilisearch, Headless Chrome)
in the same compose network to function. These are not independently accessible.

## Notes / Gotchas

- The `X-Forwarded-Proto: https` middleware is required for Karakeep (Next.js)
  to trust the proxy and generate correct redirect URIs — without it, HTTPS
  callbacks will fail.
- Video downloads can consume significant storage on `/mnt/data/karakeep`. The
  timeout is 2 hours, which accommodates long-form content.
- Meilisearch index data is stored in `/data` — this must be backed up alongside
  the app database for search to remain functional after a restore.
- `DISABLE_SIGNUPS: true` — new accounts must be created manually in the admin UI.

---
*Last Updated: 2026-06-17*