Skip to content
NoteDiscovery icon
v2.0.6App: v0.32.1Pinned DigestS3 Backup Ready

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

NoteDiscovery Helm Chart

Deploy NoteDiscovery, a self-hosted Markdown knowledge base with graph view, search, sharing, and MCP integration.

This chart packages the official ghcr.io/gamosoft/notediscovery:0.32.1 image and exposes the runtime settings that matter for Kubernetes: persistent note storage, generated or externally managed config.yaml, optional authentication, ingress/Gateway API exposure, network policy, pod disruption budget, and non-root security context.

Architecture

NoteDiscovery runs as one Python web service listening on port 8000. The upstream container stores durable notes and related files under /app/data and reads application settings from /app/config.yaml.

The default chart topology is intentionally conservative:

  • one Deployment replica with Recreate rollout strategy
  • one PersistentVolumeClaim mounted at /app/data
  • generated ConfigMap for unauthenticated config.yaml
  • ServiceAccount token automount disabled
  • non-root container security context

When authentication is enabled, the generated config.yaml is stored in a Kubernetes Secret so secret_key, password, and api_key are not rendered into a ConfigMap. For GitOps and production, prefer auth.existingSecret with a complete config.yaml key.

Install

helm repo add helmforge https://repo.helmforge.dev
helm install notediscovery helmforge/notediscovery

Forward the service for local validation:

kubectl port-forward svc/notediscovery 8000:8000

Then open http://127.0.0.1:8000.

Production Values

notediscovery:
  allowedOrigins:
    - https://notes.example.com
  defaultTheme: dracula

auth:
  enabled: true
  existingSecret: notediscovery-config
  existingSecretKey: config.yaml

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: notes.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: notediscovery-tls
      hosts:
        - notes.example.com

persistence:
  enabled: true
  size: 20Gi

resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 1
    memory: 1Gi

networkPolicy:
  enabled: true
  extraEgress:
    - to:
        - ipBlock:
            cidr: 10.0.0.0/8
      ports:
        - protocol: TCP
          port: 8443

Create the existing Secret with a complete NoteDiscovery config file:

apiVersion: v1
kind: Secret
metadata:
  name: notediscovery-config
type: Opaque
stringData:
  config.yaml: |
    app:
      name: "NoteDiscovery"
    server:
      host: "0.0.0.0"
      port: 8000
      reload: false
      allowed_origins:
        - https://notes.example.com
      debug: false
    storage:
      notes_dir: "/app/data"
      plugins_dir: "/app/data/plugins"
    search:
      enabled: true
    ui:
      autosave_delay_ms: 1000
      default_theme: "dracula"
    authentication:
      enabled: true
      secret_key: "replace-with-a-long-random-secret"
      password: "replace-with-a-strong-password"
      session_max_age: 604800
      api_key: ""

Authentication

auth.enabled=false is the default so first-time local installs start without credentials. For any shared or internet-facing deployment, enable authentication and provide either:

  • auth.secretKey and auth.password, which render into a chart-managed Secret
  • auth.existingSecret, which must contain a complete config.yaml

auth.existingSecret is preferred for production because it avoids putting secret values in Helm values files.

Storage

Back up the PersistentVolumeClaim before upgrades. NoteDiscovery stores notes and local application data under /app/data by default.

The chart blocks replicaCount > 1 unless persistence.existingClaim is set. Multiple pods require storage semantics chosen by the operator, typically a shared ReadWriteMany claim; the default generated claim is a single-writer volume.

Upgrade Notes

Upgrading to 0.32.1

NoteDiscovery 0.32.1 is an upstream release containing new features, bug fixes, and stability improvements. No breaking configuration or schema changes are introduced in this release. Review the upstream 0.32.1 release notes.

Upgrading to 0.31.7

NoteDiscovery 0.31.7 adds a homepage list view without changing the service, configuration or persistence contracts. Review the upstream 0.31.7 release and back up the data PVC before upgrading.

Generated configuration now stores plugin state under the writable data volume and bootstraps the official bundled plugins there. Existing Secrets should use storage.plugins_dir: "/app/data/plugins" (or another writable directory). The chart sets PLUGINS_DIR to notediscovery.pluginsDir, derived from persistence.mountPath when empty, so the effective path stays consistent for generated config, existing Secrets, and External Secrets. Bootstrap preserves files already present on the volume.

Back up the PVC and keep persistence.mountPath stable, then apply the new chart defaults while preserving explicit overrides:

helm repo update helmforge
helm upgrade notediscovery helmforge/notediscovery \
  --version 1.1.0 \
  --namespace notediscovery \
  --reset-then-reuse-values

Network Policy

networkPolicy.enabled=true restricts inbound HTTP traffic to the configured networkPolicy.ingressFrom peers, or to all namespaces when ingressFrom is empty. networkPolicy.extraEgress enables egress isolation and appends custom egress rules after built-in DNS and HTTPS allowances.

Documentation

Security Scan: notediscovery

Framework Score
MITRE + NSA + SOC2 87.37%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  users[Trusted users] --> edge[Ingress or Gateway API]
  edge --> service[NoteDiscovery Service]
  service --> app[Singleton NoteDiscovery Deployment]
  config[ConfigMap or Secret config.yaml] --> app
  eso[External Secrets Operator optional] -. materializes .-> config
  app --> notes[(Markdown data PVC)]
  app --> plugins[(Plugin data on PVC)]
  mcp[MCP clients] --> service
Official Contractvalues.schema.json

NoteDiscovery Values Schema Reference

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

96 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(3)

ParameterTypeDefaultDescription
image.repositorystringghcr.io/gamosoft/notediscoveryChart configuration parameter
image.tagstring0.32.1Chart configuration parameter
image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger1Chart configuration parameter

App(6)

ParameterTypeDefaultDescription
app.portinteger8000Chart configuration parameter
app.timezonestringUTCChart configuration parameter
app.commandarray-Chart configuration parameter
app.argsarray-Chart configuration parameter
app.envarray-Chart configuration parameter
app.envFromarray-Chart configuration parameter

Notediscovery(7)

ParameterTypeDefaultDescription
notediscovery.appNamestringNoteDiscoveryChart configuration parameter
notediscovery.allowedOriginsarray-Chart configuration parameter
notediscovery.debugbooleanfalseChart configuration parameter
notediscovery.searchEnabledbooleantrueChart configuration parameter
notediscovery.autosaveDelayMsinteger1000Chart configuration parameter
notediscovery.defaultThemestringlightChart configuration parameter
notediscovery.pluginsDirstring""Chart configuration parameter

Authentication(7)

ParameterTypeDefaultDescription
auth.enabledbooleanfalseChart configuration parameter
auth.secretKeystring""Chart configuration parameter
auth.passwordstring""Chart configuration parameter
auth.apiKeystring""Chart configuration parameter
auth.sessionMaxAgeinteger604800Chart configuration parameter
auth.existingSecretstring""Chart configuration parameter
auth.existingSecretKeystringconfig.yamlChart configuration parameter

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledbooleantrueChart configuration parameter
persistence.sizestring5GiChart configuration parameter
persistence.storageClassstring""Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring""Chart configuration parameter
persistence.mountPathstring/app/dataChart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createbooleantrueChart 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.portinteger8000Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicystring-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
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(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledbooleanfalseChart configuration parameter
gatewayAPI.httpRoutesarray-Chart configuration parameter

External Secrets(4)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring1hChart configuration parameter
externalSecrets.itemsarray-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(2)

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

Container Security(7)

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
securityContext.runAsGroupinteger-Chart configuration parameter
securityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined

Pdb(2)

ParameterTypeDefaultDescription
pdb.enabledbooleanfalseChart configuration parameter
pdb.minAvailableany-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledbooleanfalseChart configuration parameter
networkPolicy.ingressFromarray-Chart configuration parameter
networkPolicy.extraEgressarray-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