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.1security 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_SECRETandMEILI_MASTER_KEYwith 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
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.
| --- | --- | --- |
| 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 SyncedVerified 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
endKaraKeep Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global settings shared by the chart. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | ghcr.io/karakeep-app/karakeep | Chart configuration parameter |
| image.tag | string | "" | Chart configuration parameter |
| image.digest | string | - | Chart configuration parameter |
| image.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Container Ports(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| containerPorts.http | integer | 3000 | Chart configuration parameter |
Karakeep(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| karakeep.nextAuthUrl | string | "" | Public URL of the Karakeep instance |
| karakeep.browserConnectOnDemand | boolean | true | Chart configuration parameter |
| karakeep.existingSecret | string | "" | Existing secret containing nextauth-secret and meili-master-key |
| karakeep.existingSecretNextAuthKey | string | nextauth-secret | Chart configuration parameter |
| karakeep.existingSecretMeiliMasterKey | string | meili-master-key | Chart configuration parameter |
| karakeep.extraEnv | array | - | Chart configuration parameter |
Meilisearch(14)
| Parameter | Type | Default | Description |
|---|---|---|---|
| meilisearch.enabled | boolean | true | Chart configuration parameter |
| meilisearch.image.repository | string | docker.io/getmeili/meilisearch | Chart configuration parameter |
| meilisearch.image.tag | string | v1.53.0 | Chart configuration parameter |
| meilisearch.image.digest | string | - | Chart configuration parameter |
| meilisearch.image.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| meilisearch.port | integer | 7700 | Chart configuration parameter |
| meilisearch.environment | string | development | Chart configuration parameter Allowed: developmentproduction |
| meilisearch.upgradeDb | boolean | true | Chart configuration parameter |
| meilisearch.extraEnv | array | - | Chart configuration parameter |
| meilisearch.securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| meilisearch.securityContext.capabilities.drop | array | - | Chart configuration parameter |
| meilisearch.securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| meilisearch.securityContext.runAsUser | integer | - | Chart configuration parameter |
| meilisearch.resources | object | - | Chart configuration parameter |
Chromium(13)
| Parameter | Type | Default | Description |
|---|---|---|---|
| chromium.enabled | boolean | true | Chart configuration parameter |
| chromium.image.repository | string | ghcr.io/karakeep-app/karakeep-chrome | Chart configuration parameter |
| chromium.image.tag | string | 154.0.8037.57-r1 | Chart configuration parameter |
| chromium.image.digest | string | - | Chart configuration parameter |
| chromium.image.pullPolicy | string | IfNotPresent | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| chromium.args | array | - | Chart configuration parameter |
| chromium.securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| chromium.securityContext.capabilities.drop | array | - | Chart configuration parameter |
| chromium.securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| chromium.securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| chromium.securityContext.runAsUser | integer | - | Chart configuration parameter |
| chromium.securityContext.runAsGroup | integer | - | Chart configuration parameter |
| chromium.resources | object | - | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | true | Chart configuration parameter |
| persistence.size | string | 10Gi | Chart configuration parameter |
| persistence.storageClass | string | "" | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | "" | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | false | Chart configuration parameter |
| serviceAccount.name | string | "" | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | false | Chart configuration parameter |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | ClusterIP | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | 80 | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | stringnull | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStacknull |
| service.ipFamilies | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | false | Chart configuration parameter |
| ingress.ingressClassName | string | traefik | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | false | Chart configuration parameter |
| gatewayAPI.parentRefs | array | - | Chart configuration parameter |
| gatewayAPI.hostnames | array | - | Chart configuration parameter |
| gatewayAPI.paths | array | - | Chart configuration parameter |
| gatewayAPI.annotations | object | - | Chart configuration parameter |
Health Probes(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | - | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter Allowed: RuntimeDefaultLocalhostUnconfined |
Container Security(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| securityContext.runAsUser | integer | - | Chart configuration parameter |
Network Policy(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | true | Chart configuration parameter |
| networkPolicy.ingressFrom | array | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | "" | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | 30 | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
External Secrets(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Chart configuration parameter |
| externalSecrets.apiVersion | string | external-secrets.io/v1 | Chart configuration parameter |
| externalSecrets.refreshInterval | string | 0 | Chart configuration parameter |
| externalSecrets.secretStoreRef.name | string | "" | Chart configuration parameter |
| externalSecrets.secretStoreRef.kind | string | SecretStore | Chart configuration parameter Allowed: SecretStoreClusterSecretStore |
| externalSecrets.target.creationPolicy | string | Owner | Chart configuration parameter |
| externalSecrets.data | array | - | Chart configuration parameter |
| externalSecrets.annotations | object | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.