Skip to content
Changedetection icon
v1.1.22App: v0.60.9Pinned DigestS3 Backup Ready

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

changedetection.io Helm Chart

Deploy changedetection.io on Kubernetes using the official dgtlmoon/changedetection.io container image. Monitor websites for changes, track price or stock updates, run selective content filters, and send notifications through email, Slack, Discord, Telegram, webhooks, and 90+ Apprise services.

Features

  • Website monitoring — detect content changes on any URL
  • 90+ notification channels — via built-in Apprise library
  • Optional JavaScript rendering — Playwright browser sidecar for dynamic sites
  • JSON datastore — zero external database dependencies
  • Persistent storage — snapshots and history on PVC
  • Ingress support — TLS with cert-manager
  • Gateway API support — optional HTTPRoute for platform Gateway deployments
  • Dual-stack Service support — optional ipFamilyPolicy and ipFamilies
  • External Secrets integration — render ESO resources for environment-backed configuration
  • Configurable probes — startup, readiness, and liveness checks
  • Runtime tuning — fetch workers, recheck interval, timezone, labels, annotations, resources, scheduling, and extra manifests

Installation

HTTPS repository:

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

OCI registry:

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

Basic Example

# values.yaml — default values are sufficient for basic usage
changedetection:
  baseUrl: "https://cd.example.com"

After deploying:

kubectl port-forward svc/<release>-changedetection 5000:80
# Open http://localhost:5000

Architecture

The chart runs one changedetection.io container behind a ClusterIP Service and mounts /datastore from a PVC by default. Ingress or Gateway API can publish the Service. When browser rendering is enabled, Sockpuppet runs as a sidecar and accepts WebSocket connections only inside the pod; no Service exposes its listener. See DESIGN.md for the complete trust and production boundaries.

JavaScript Rendering

Enable the Playwright browser sidecar for monitoring JavaScript-heavy sites:

browser:
  enabled: true
  port: 3000

The sidecar runs the upstream-recommended docker.io/dgtlmoon/sockpuppetbrowser and the main container receives PLAYWRIGHT_DRIVER_URL automatically. Keep browser resources sized separately from the application container when JavaScript rendering is used heavily. The chart passes browser.port to the Sockpuppet process with --port, binds its WebSocket listener to 127.0.0.1, and does not publish it through the Service. When the browser is enabled, neither application listener may use Sockpuppet's fixed statistics port 8080.

The browser sidecar runs as the pinned image's non-root chrome user, disables privilege escalation, and drops all Linux capabilities by default. Override browser.securityContext only for a verified image or runtime requirement.

Persistence

changedetection.io stores its JSON settings and watch files, snapshots, and watch history in /datastore. Persistence is enabled by default:

persistence:
  enabled: true
  size: 10Gi
  storageClass: ""

For disposable test environments, disable persistence to use an emptyDir:

persistence:
  enabled: false

Because the datastore is written by one application instance, this chart intentionally deploys a single replica with the Recreate strategy. Do not scale the workload horizontally unless the upstream application storage model changes.

Ingress

changedetection:
  baseUrl: "https://cd.example.com"

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

Set changedetection.baseUrl to the public URL used by users and notification links.

Gateway API

Use Gateway API when your platform routes applications through shared Gateway resources:

changedetection:
  baseUrl: "https://cd.example.com"

gateway:
  enabled: true
  parentRefs:
    - name: shared-gateway
      namespace: ingress
  hostnames:
    - cd.example.com

The chart renders a single HTTPRoute named after the release and points it to the chart Service. Keep Ingress and Gateway API disabled by default and enable only the routing path managed by the cluster.

External Secrets

The chart can render ExternalSecret resources for upstream-supported environment variables and automatically consume the produced Secret:

externalSecrets:
  enabled: true
  secretStoreRef:
    name: vault
    kind: ClusterSecretStore
  target:
    name: changedetection-env
    creationPolicy: Owner
  data:
    - secretKey: LOGGER_LEVEL
      remoteRef:
        key: changedetection/app
        property: loggerLevel

Use this for notification credentials or other sensitive values that should be owned by External Secrets Operator instead of committed into values files.

Dual-Stack Service

Clusters with IPv4/IPv6 networking can opt into Kubernetes Service dual-stack:

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

Runtime Configuration

changedetection:
  fetchWorkers: 10
  minimumSecondsRecheckTime: "180"
  timezone: "America/Sao_Paulo"
  locale: C
  envFrom:
    - secretRef:
        name: changedetection-env
  extraEnv:
    - name: LOGGER_LEVEL
      value: INFO

Use changedetection.extraEnv for upstream-supported environment variables that are not exposed as first-class chart values, and changedetection.envFrom for pre-created or externally materialized Secrets.

The chart keeps the container non-root by default and sets PIP_USER=true with PYTHONUSERBASE=/datastore/.python-userbase. This gives the upstream EXTRA_PACKAGES entrypoint hook a writable Python user install path without requiring root privileges:

changedetection:
  extraEnv:
    - name: EXTRA_PACKAGES
      value: "chardet==5.2.0"

Security And Scheduling

The chart exposes standard Kubernetes controls for production placement and hardening:

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

podSecurityContext: {}
nodeSelector: {}
tolerations: []
affinity: {}
topologySpreadConstraints: []
priorityClassName: ""

Probes

Startup, liveness, and readiness probes are enabled by default and use the HTTP container port through TCP socket checks. Tune probe timings for slow storage or large existing datastores:

probes:
  startup:
    failureThreshold: 30
  liveness:
    periodSeconds: 15
  readiness:
    periodSeconds: 10
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/dgtlmoon/changedetection.io | changedetection.io image repository | | image.tag | 0.60.9 | changedetection.io image tag | | image.pullPolicy | IfNotPresent | Image pull policy | | changedetection.port | 5000 | Application port | | changedetection.baseUrl | "" | Public base URL | | changedetection.fetchWorkers | 10 | Concurrent fetch workers | | changedetection.minimumSecondsRecheckTime | "" | Minimum seconds between checks | | changedetection.timezone | "" | Container timezone via TZ | | changedetection.locale | C | Locale assigned to LANG and LC_ALL | | changedetection.defaultWatches.enabled | false | Let upstream create sample watches on a fresh datastore | | changedetection.extraEnv | [] | Extra environment variables | | changedetection.envFrom | [] | Extra envFrom sources | | browser.enabled | false | Enable Playwright browser sidecar | | browser.port | 3000 | Loopback Sockpuppet WebSocket listener; when enabled it must differ from changedetection.port and Sockpuppet statistics port 8080 | | browser.image.repository | docker.io/dgtlmoon/sockpuppetbrowser | Browser sidecar image repository | | browser.image.tag | 0.0.3 | Browser sidecar image tag | | browser.image.digest | sha256:1d8f72d2ce2085faed4232e5ae1e65c02efe5b831a18e127829b267c260b4fb2 | Immutable browser sidecar image index digest | | persistence.enabled | true | Enable persistence for /datastore | | persistence.size | 10Gi | PVC size | | persistence.storageClass | "" | PVC storage class | | persistence.existingClaim | "" | Existing PVC name | | service.type | ClusterIP | Kubernetes Service type | | service.port | 80 | HTTP Service port | | service.ipFamilyPolicy | unset | Optional Service IP family policy | | service.ipFamilies | [] | Optional Service IP families | | serviceAccount.automountServiceAccountToken | false | Mount the Kubernetes API token into the pod | | ingress.enabled | false | Enable ingress | | gateway.enabled | false | Enable Gateway API HTTPRoute | | externalSecrets.enabled | false | Render ExternalSecret resources | | externalSecrets.secretStoreRef.name | "" | Required SecretStore name when ExternalSecrets is enabled | | externalSecrets.target.name | "" | Target Secret name, defaults to release-derived name | | probes.*.enabled | true | Enable startup, readiness, and liveness probes | | resources.requests.cpu | 100m | Main container CPU request | | resources.requests.memory | 256Mi | Main container memory request | | resources.limits.cpu | 1000m | Main container CPU limit | | resources.limits.memory | 1Gi | Main container memory limit | | podSecurityContext.fsGroup | 1000 | Writable group for the /datastore volume | | securityContext.runAsNonRoot | true | Run the main container without root privileges | | securityContext.allowPrivilegeEscalation | false | Prevent privilege escalation | | securityContext.capabilities.drop | [ALL] | Drop Linux capabilities by default | | browser.securityContext.runAsUser | 1000 | Run the browser as the image's chrome UID | | browser.securityContext.runAsGroup | 1000 | Run the browser as the image's chrome GID | | browser.securityContext.runAsNonRoot | true | Require the browser image's non-root user | | browser.securityContext.allowPrivilegeEscalation | false | Prevent browser-sidecar privilege escalation | | browser.securityContext.capabilities.drop | [ALL] | Drop browser-sidecar Linux capabilities | | extraManifests | [] | Additional manifests rendered with the release |

Upgrade Notes

Version 0.60.9 fixes decimal-comma price detection, adds a Unix-time notification filter and exposes the language selector on the login page. It also updates security-sensitive runtime dependencies. It does not change the service port or /datastore persistence contract. Review the 0.60.9 notes.

Version 0.60.3 includes the intervening watch/tag loading, XML parsing, CSRF/XSS protections, browser and UTF-8 backup fixes since 0.55.8. Back up the complete /datastore before upgrading: changedetection.json, watch/tag directories and snapshots belong together. Restore that backup with its matching old image for rollback; reverting only the tag does not reverse storage migrations.

Upstream consistently blocks private, loopback and other restricted target addresses by default. Existing internal-site monitors may need an explicit opt-in:

changedetection:
  extraEnv:
    - name: ALLOW_IANA_RESTRICTED_ADDRESSES
      value: "true"

Use that setting only when internal monitoring is intended and application access is controlled. The chart keeps the upstream restriction enabled by default. PLAYWRIGHT_BYPASS_CSP defaults to true upstream; set it to false through changedetection.extraEnv when the remote browser does not support CSP bypass.

Limitations

  • Single instance only — the JSON datastore requires a single application writer
  • Storage grows — each snapshot consumes disk space; plan PVC size accordingly
  • Browser rendering costs more — enabling the browser sidecar increases CPU and memory consumption

Troubleshooting

  • If probes fail after changing changedetection.port, confirm the rendered PORT environment variable and named http container port match.
  • If JavaScript watches fail while plain HTTP watches work, inspect the browser container logs and confirm PLAYWRIGHT_DRIVER_URL uses browser.port.
  • If watches disappear after rescheduling, verify that the pod mounts the intended PVC at /datastore and that the StorageClass retained its volume.
  • If internal targets are blocked, keep the default restriction unless the deployment is access-controlled and explicitly requires ALLOW_IANA_RESTRICTED_ADDRESSES=true.

Security Scan

Security Scan: changedetection

Framework Score
MITRE + NSA + SOC2 87.88%

Rendered manifests scanned with Kubescape 4.0.14 on 2026-09-15.

Local details:

Framework Score
MITRE 100.00%
NSA 85.00%
SOC2 80.00%

The remaining findings are expected for this workload profile: changedetection.io needs a writable datastore for JSON files and snapshots, NetworkPolicy is supplied by the platform layer, and ServiceAccount token hardening remains configurable by cluster policy.

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  user[Users and automation] --> route[Ingress or HTTPRoute]
  route --> service[Service]
  service --> app[changedetection.io]
  app --> data[(Datastore PVC)]
  app -. optional WebSocket .-> browser[Sockpuppet browser sidecar]
  secret[Secret or ExternalSecret] --> app
Official Contractvalues.schema.json

Changedetection Values Schema Reference

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

107 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/dgtlmoon/changedetection.ioChart configuration parameter
image.tagstring0.60.9Chart configuration parameter
image.pullPolicystringIfNotPresentChart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Changedetection(9)

ParameterTypeDefaultDescription
changedetection.portinteger5000Chart configuration parameter
changedetection.baseUrlstring""Chart configuration parameter
changedetection.fetchWorkersinteger10Chart configuration parameter
changedetection.minimumSecondsRecheckTimestring""Chart configuration parameter
changedetection.timezonestring""Chart configuration parameter
changedetection.localestringCChart configuration parameter
changedetection.envFromarray-Chart configuration parameter
changedetection.defaultWatches.enabledbooleanfalseLet changedetection.io create upstream sample watches on a fresh datastore.
changedetection.extraEnvarray-Chart configuration parameter

Browser(15)

ParameterTypeDefaultDescription
browser.enabledbooleanfalseChart configuration parameter
browser.portinteger3000Chart configuration parameter
browser.image.repositorystring-Chart configuration parameter
browser.image.tagstring-Chart configuration parameter
browser.image.digeststring-Chart configuration parameter
browser.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
browser.resources.requests.cpustringnumber-Chart configuration parameter
browser.resources.requests.memorystringnumber-Chart configuration parameter
browser.resources.limits.cpustringnumber-Chart configuration parameter
browser.resources.limits.memorystringnumber-Chart configuration parameter
browser.securityContext.runAsUserinteger1000Chart configuration parameter
browser.securityContext.runAsGroupinteger1000Chart configuration parameter
browser.securityContext.runAsNonRootbooleantrueChart configuration parameter
browser.securityContext.allowPrivilegeEscalationbooleanfalseChart configuration parameter
browser.securityContext.capabilities.droparray["ALL"]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(6)

ParameterTypeDefaultDescription
gateway.enabledbooleanfalseChart configuration parameter
gateway.annotationsobject-Chart configuration parameter
gateway.parentRefsarray-Chart configuration parameter
gateway.hostnamesarray-Chart configuration parameter
gateway.pathstring/Chart configuration parameter
gateway.pathTypestringPathPrefixChart configuration parameter

External Secrets(9)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring1hChart configuration parameter
externalSecrets.secretStoreRef.namestring""Chart configuration parameter
externalSecrets.secretStoreRef.kindstringSecretStoreChart configuration parameter
externalSecrets.target.namestring""Chart configuration parameter
externalSecrets.target.creationPolicystringOwnerChart configuration parameter
externalSecrets.dataarray-Chart configuration parameter
externalSecrets.dataFromarray-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(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystringnumber-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystringnumber-Chart configuration parameter

Pod Security(4)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger1000Chart configuration parameter
podSecurityContext.fsGroupChangePolicystringOnRootMismatchChart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestringRuntimeDefaultChart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined
podSecurityContext.seccompProfile.localhostProfilestring-Chart configuration parameter

Container Security(7)

ParameterTypeDefaultDescription
securityContext.runAsUserinteger1000Chart configuration parameter
securityContext.runAsGroupinteger1000Chart configuration parameter
securityContext.runAsNonRootbooleantrueChart configuration parameter
securityContext.allowPrivilegeEscalationbooleanfalseChart configuration parameter
securityContext.readOnlyRootFilesystembooleanfalseChart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-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