Skip to content
KaraKeep icon
v1.3.1App: v0.34.1Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Karakeep Helm Chart

Deploy Karakeep, formerly Hoarder, on Kubernetes using the official ghcr.io/karakeep-app/karakeep container image. Karakeep provides bookmark management, full-text archive search, web page capture, and optional AI tagging in a single-writer application pod.

Current application version: 0.34.1.

Features

  • Official Karakeep image pinned to the 0.34.1 security release and digest
  • Optional Meilisearch sidecar for full-text search
  • Optional official Karakeep Chrome sidecar for screenshots and page archiving
  • SQLite and uploaded content stored on a PersistentVolumeClaim
  • Generated NEXTAUTH_SECRET and MEILI_MASTER_KEY with lookup-based reuse on upgrades
  • Existing Secret and External Secrets Operator paths for production credentials
  • Ingress, Gateway API, dual-stack Service, scheduling, and resource controls
  • Configurable Karakeep and Meilisearch listeners with runtime validation
  • Non-root containers, seccomp, dropped capabilities, token-free ServiceAccount, and an ingress NetworkPolicy by default

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install karakeep helmforge/karakeep -f values.yaml

OCI registry:

helm install karakeep oci://ghcr.io/helmforgedev/helm/karakeep -f values.yaml

Examples

The chart includes example values under examples/:

  • examples/simple.yaml - local or private-network deployment with explicit resources.
  • examples/ingress.yaml - TLS ingress with sidecars enabled.
  • examples/ai-tagging.yaml - AI tagging through Secret-backed environment variables.
  • examples/external-secrets.yaml - External Secrets Operator projection for auth and search credentials.

Render an example before adapting it:

helm template karakeep charts/karakeep -f charts/karakeep/examples/ingress.yaml

Architecture Guides

Basic Configuration

For local testing through port-forwarding:

karakeep:
  nextAuthUrl: "http://localhost:3000"

Then access the web UI:

kubectl port-forward svc/<release>-karakeep 3000:80

For production, karakeep.nextAuthUrl must match the exact external URL users open in the browser, including https:// when TLS is enabled.

Sidecars

Meilisearch and Chromium are enabled by default because they provide Karakeep's search and archive capture experience. They also increase pod memory needs. Set resources for each container in production:

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

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

chromium:
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: "1"
      memory: 1Gi

Disable sidecars only when the workload can operate without their features:

meilisearch:
  enabled: false

chromium:
  enabled: false
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

| --- | --- | --- | | image.repository | ghcr.io/karakeep-app/karakeep | Main Karakeep image | | image.tag | "0.34.1" | Main Karakeep image tag | | containerPorts.http | 3000 | Karakeep process listener port | | karakeep.nextAuthUrl | "" | Public URL of the Karakeep instance | | karakeep.browserConnectOnDemand | true | Connect to Chromium only when crawling needs it | | karakeep.existingSecret | "" | Existing secret with auth and Meilisearch keys | | karakeep.extraEnv | [] | Extra environment variables for AI and advanced configuration | | meilisearch.enabled | true | Enable the Meilisearch sidecar | | meilisearch.port | 7700 | Meilisearch process listener port | | meilisearch.environment | development | Meilisearch runtime environment | | meilisearch.upgradeDb | true | Upgrade an older on-disk Meilisearch database at startup | | meilisearch.extraEnv | [] | Extra non-reserved Meilisearch environment variables | | chromium.enabled | true | Enable the Chromium sidecar | | networkPolicy.enabled | true | Restrict ingress to the HTTP port | | persistence.enabled | true | Enable persistence for SQLite, uploads, and Meilisearch data | | persistence.size | 10Gi | PVC size | | ingress.enabled | false | Enable Ingress | | gatewayAPI.enabled | false | Enable Gateway API HTTPRoute | | externalSecrets.enabled | false | Render ExternalSecret for app credentials |

Image tags and digests form a pair. When overriding image.tag, meilisearch.image.tag, or chromium.image.tag, also set the matching digest to the digest published for that exact image tag; Kubernetes resolves the digest as the deployed image identity.

Security Scan

Security Scan: Kubescape on rendered default manifests.

Framework Score
MITRE + NSA + SOC2 87.878784%

Resource requests and limits remain unset because sizing depends on archive and search load. The chart otherwise enables non-root execution, seccomp, dropped capabilities, disabled API token mounting, and an ingress NetworkPolicy by default.

Upgrade Notes

Karakeep 0.34.1 updates Node.js to fix one Brotli memory-safety vulnerability and three TLS hostname-validation bypasses. This chart also completes the 0.34.0 migration from Browserless to the official karakeep-chrome image. Back up the /data PVC before upgrading. Before upgrading an existing 0.33.x installation, resolve any 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 the migration. Mobile sessions and API keys are unaffected.

Quality Gates

Before proposing a merge for this chart, run:

make validate-chart CHART=karakeep
make standards-check CHART=karakeep
make deps-check CHART=karakeep
make site-sync-check CHART=karakeep

Persistence

Karakeep stores SQLite, uploads, queue state, and optional sidecar data on the PVC mounted at /data. The Deployment uses strategy.type=Recreate because the default storage model is single-writer.

Use an existing PVC when migrating from another release:

persistence:
  existingClaim: my-karakeep-pvc

External Secrets

Use externalSecrets.enabled=true only with karakeep.existingSecret. The ExternalSecret must populate both nextauth-secret and meili-master-key when Meilisearch is enabled.

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

Limitations

  • Single replica by default; SQLite and the shared PVC are not a concurrent writer architecture.
  • Ingress and Gateway API expose HTTP routing only; authentication and network boundaries outside Karakeep are platform responsibilities.
  • AI providers are configured through karakeep.extraEnv; this chart does not create provider-specific API key Secrets.

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart TD
    Client[Browser or API client] --> Edge[Port-forward, Ingress, or HTTPRoute]
    Edge --> Service[ClusterIP Service]
    Service --> App[Karakeep container<br/>containerPorts.http]

    subgraph Pod[Karakeep Deployment: one replica, Recreate]
        App --> Search[Optional Meilisearch sidecar<br/>meilisearch.port]
        App --> Browser[Optional Karakeep Chrome sidecar<br/>127.0.0.1:9222]
        Secret[Secret] --> App
        Secret --> Search
        PVC[PVC mounted at /data] --> App
        PVC --> Search
    end
Official Contractvalues.schema.json

KaraKeep Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

112 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Image(4)

ParameterTypeDefaultDescription
image.repositorystringghcr.io/karakeep-app/karakeepChart configuration parameter
image.tagstring""Chart configuration parameter
image.digeststring-Chart configuration parameter
image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger3000Chart configuration parameter

Karakeep(6)

ParameterTypeDefaultDescription
karakeep.nextAuthUrlstring""Public URL of the Karakeep instance
karakeep.browserConnectOnDemandbooleantrueChart configuration parameter
karakeep.existingSecretstring""Existing secret containing nextauth-secret and meili-master-key
karakeep.existingSecretNextAuthKeystringnextauth-secretChart configuration parameter
karakeep.existingSecretMeiliMasterKeystringmeili-master-keyChart configuration parameter
karakeep.extraEnvarray-Chart configuration parameter

Meilisearch(14)

ParameterTypeDefaultDescription
meilisearch.enabledbooleantrueChart configuration parameter
meilisearch.image.repositorystringdocker.io/getmeili/meilisearchChart configuration parameter
meilisearch.image.tagstringv1.53.0Chart configuration parameter
meilisearch.image.digeststring-Chart configuration parameter
meilisearch.image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever
meilisearch.portinteger7700Chart configuration parameter
meilisearch.environmentstringdevelopmentChart configuration parameter
Allowed:developmentproduction
meilisearch.upgradeDbbooleantrueChart configuration parameter
meilisearch.extraEnvarray-Chart configuration parameter
meilisearch.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
meilisearch.securityContext.capabilities.droparray-Chart configuration parameter
meilisearch.securityContext.runAsNonRootboolean-Chart configuration parameter
meilisearch.securityContext.runAsUserinteger-Chart configuration parameter
meilisearch.resourcesobject-Chart configuration parameter

Chromium(13)

ParameterTypeDefaultDescription
chromium.enabledbooleantrueChart configuration parameter
chromium.image.repositorystringghcr.io/karakeep-app/karakeep-chromeChart configuration parameter
chromium.image.tagstring154.0.8037.57-r1Chart configuration parameter
chromium.image.digeststring-Chart configuration parameter
chromium.image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever
chromium.argsarray-Chart configuration parameter
chromium.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
chromium.securityContext.capabilities.droparray-Chart configuration parameter
chromium.securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
chromium.securityContext.runAsNonRootboolean-Chart configuration parameter
chromium.securityContext.runAsUserinteger-Chart configuration parameter
chromium.securityContext.runAsGroupinteger-Chart configuration parameter
chromium.resourcesobject-Chart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueChart configuration parameter
persistence.sizestring10GiChart configuration parameter
persistence.storageClassstring""Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring""Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createbooleanfalseChart configuration parameter
serviceAccount.namestring""Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenbooleanfalseChart configuration parameter

Service & Networking(5)

ParameterTypeDefaultDescription
service.typestringClusterIPChart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger80Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystringnull-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStacknull
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledbooleanfalseChart configuration parameter
ingress.ingressClassNamestringtraefikChart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Gateway API(5)

ParameterTypeDefaultDescription
gatewayAPI.enabledbooleanfalseChart configuration parameter
gatewayAPI.parentRefsarray-Chart configuration parameter
gatewayAPI.hostnamesarray-Chart configuration parameter
gatewayAPI.pathsarray-Chart configuration parameter
gatewayAPI.annotationsobject-Chart configuration parameter

Health Probes(15)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined

Container Security(5)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledbooleantrueChart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring""Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger30Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

External Secrets(8)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring0Chart configuration parameter
externalSecrets.secretStoreRef.namestring""Chart configuration parameter
externalSecrets.secretStoreRef.kindstringSecretStoreChart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystringOwnerChart configuration parameter
externalSecrets.dataarray-Chart configuration parameter
externalSecrets.annotationsobject-Chart configuration parameter