Karakeep

AI-powered bookmark manager. Karakeep saves links with full-text content archival, automatic screenshots via the official Karakeep Chrome image, full-text search via Meilisearch, and optional AI-driven automatic tagging. All data is stored in SQLite on a single persistent volume. The chart currently deploys Karakeep 0.34.1.

Architecture

Karakeep runs as a single pod with optional sidecars sharing the same PVC:

• karakeep — main application (Next.js)
• meilisearch (optional) — full-text search engine, indexes archived content
• chromium (optional) — official Karakeep Chrome image for web page screenshots and archiving

Key Features

• Meilisearch sidecar — optional full-text search across bookmarks and archived content
• Chromium sidecar — optional headless browser for automatic web page screenshots
• AI tagging — automatic categorization via OpenAI or Ollama (configured via extraEnv)
• SQLite storage — embedded database, no external database required
• Persistent storage — single PVC shared by all containers
• Ingress support — TLS via cert-manager with configurable ingress class
• External Secrets — optional ESO projection for auth and Meilisearch credentials
• Runtime port contracts — configurable Karakeep and Meilisearch listeners, validated in-cluster
• Secure defaults — non-root containers, seccomp, dropped capabilities, token-free ServiceAccount, and NetworkPolicy

Operational Patterns

The examples below cover the supported Karakeep operating modes: full sidecar mode, lightweight mode, AI tagging, explicit resource limits, TLS ingress, Gateway API, and External Secrets Operator credentials. The playground exposes the same high-impact settings so operators can generate a focused values file without starting from the complete values contract.

Security Scan

Security Scan: Kubescape on rendered default manifests.

The chart enables container hardening, runtime-default seccomp, disabled API token mounting, and an ingress NetworkPolicy by default. Resource requests and limits remain workload-specific and should be set in production.

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install karakeep helmforge/karakeep

OCI registry:

helm install karakeep oci://ghcr.io/helmforgedev/helm/karakeep

Deployment Examples

# values.yaml — Karakeep with Meilisearch and Chromium (default)
karakeep:
  nextAuthUrl: 'https://karakeep.example.com'

meilisearch:
  enabled: true
  # Allows the pinned image to migrate an older on-disk database.
  upgradeDb: true

chromium:
  enabled: true

persistence:
  enabled: true
  size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: karakeep.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: karakeep-tls
      hosts:
        - karakeep.example.com

# values.yaml — Lightweight mode without sidecars
# Suitable for resource-constrained environments (ARM, Raspberry Pi)
# Full-text search and automatic screenshots will be unavailable.
karakeep:
  nextAuthUrl: 'https://karakeep.example.com'

meilisearch:
  enabled: false

chromium:
  enabled: false

persistence:
  enabled: true
  size: 5Gi

resources:
  requests:
    memory: 256Mi
    cpu: 100m
  limits:
    memory: 512Mi
    cpu: 500m

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: karakeep.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Karakeep with OpenAI automatic tagging
karakeep:
  nextAuthUrl: 'https://karakeep.example.com'
  extraEnv:
    # OpenAI integration for automatic AI tagging
    - name: OPENAI_API_KEY
      valueFrom:
        secretKeyRef:
          name: karakeep-ai-secret
          key: openai-api-key
    - name: OPENAI_BASE_URL
      value: 'https://api.openai.com/v1'

    # Alternative: use Ollama for local AI inference
    # - name: OLLAMA_BASE_URL
    #   value: 'http://ollama.ollama.svc:11434'
    # - name: INFERENCE_TEXT_MODEL
    #   value: 'llama3.2'

meilisearch:
  enabled: true

chromium:
  enabled: true

persistence:
  enabled: true
  size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: karakeep.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Production setup with explicit resource limits per container
karakeep:
  nextAuthUrl: 'https://karakeep.example.com'

meilisearch:
  enabled: true
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
    limits:
      memory: 512Mi
      cpu: 500m

chromium:
  enabled: true
  resources:
    requests:
      memory: 512Mi
      cpu: 250m
    limits:
      memory: 1Gi
      cpu: 1000m

resources:
  requests:
    memory: 256Mi
    cpu: 100m
  limits:
    memory: 512Mi
    cpu: 500m

persistence:
  enabled: true
  size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: karakeep.example.com
      paths:
        - path: /
          pathType: Prefix

Configuration Reference

Core

Image

Karakeep Configuration

Meilisearch Sidecar

Chromium Sidecar

Persistence

All containers in the pod share the same PVC. SQLite database, Meilisearch index, and uploaded files are all stored within this volume.

Service

Ingress

Gateway API

Use gatewayAPI.enabled to render a native Kubernetes Gateway API HTTPRoute for Karakeep. Ingress stays disabled by default and can coexist with the route during migrations.

gatewayAPI:
  enabled: true
  parentRefs:
    - name: shared-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - karakeep.example.com
  paths:
    - type: PathPrefix
      value: /

Dual-Stack Networking

Karakeep’s Service supports Kubernetes dual-stack networking through optional service.ipFamilyPolicy and service.ipFamilies values. Defaults omit both fields so existing installs inherit cluster defaults.

service:
  ipFamilyPolicy: PreferDualStack

Probes

Resources and Security

These values apply to the main Karakeep container. Set meilisearch.resources and chromium.resources separately for the sidecars.

Service Account

Network Policy

The default ingress policy admits the named HTTP port from any namespace, preserving compatibility with ingress controllers while blocking other inbound pod ports. Restrict networkPolicy.ingressFrom for a tighter production boundary. Egress remains open because web archiving and optional AI providers require arbitrary external destinations.

Scheduling

Extra

External Secrets

Karakeep can render an External Secrets Operator ExternalSecret that projects NEXTAUTH_SECRET and MEILI_MASTER_KEY into the Kubernetes Secret configured by karakeep.existingSecret.

karakeep:
  existingSecret: karakeep-app-secret

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  data:
    - secretKey: nextauth-secret
      remoteRef:
        key: karakeep/credentials
        property: nextauth-secret
    - secretKey: meili-master-key
      remoteRef:
        key: karakeep/credentials
        property: meili-master-key

Common Issues

Upgrade Notes

Karakeep 0.34.1 includes the Node.js security fixes described above. The chart also replaces Browserless with the official karakeep-chrome image introduced by the upstream 0.34.0 migration. Before upgrading from 0.33.x, back up /data and resolve accounts whose email addresses differ only by letter case; the automatic migration lowercases addresses and conflicting accounts can lock users out. All web users must sign in again after migration, while mobile sessions and API keys are unaffected. Verify login, search, and a new screenshot after rollout.

More Information

• Karakeep Official Website
• Karakeep Documentation
• Karakeep GitHub Repository
• HelmForge Karakeep Chart Source