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
ipFamilyPolicyandipFamilies - 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
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/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 renderedPORTenvironment variable and namedhttpcontainer port match. - If JavaScript watches fail while plain HTTP watches work, inspect the
browsercontainer logs and confirmPLAYWRIGHT_DRIVER_URLusesbrowser.port. - If watches disappear after rescheduling, verify that the pod mounts the
intended PVC at
/datastoreand 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 SyncedVerified 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
Changedetection 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(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | ghcr.io/dgtlmoon/changedetection.io | Chart configuration parameter |
| image.tag | string | 0.60.9 | 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 |
Changedetection(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| changedetection.port | integer | 5000 | Chart configuration parameter |
| changedetection.baseUrl | string | "" | Chart configuration parameter |
| changedetection.fetchWorkers | integer | 10 | Chart configuration parameter |
| changedetection.minimumSecondsRecheckTime | string | "" | Chart configuration parameter |
| changedetection.timezone | string | "" | Chart configuration parameter |
| changedetection.locale | string | C | Chart configuration parameter |
| changedetection.envFrom | array | - | Chart configuration parameter |
| changedetection.defaultWatches.enabled | boolean | false | Let changedetection.io create upstream sample watches on a fresh datastore. |
| changedetection.extraEnv | array | - | Chart configuration parameter |
Browser(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| browser.enabled | boolean | false | Chart configuration parameter |
| browser.port | integer | 3000 | Chart configuration parameter |
| browser.image.repository | string | - | Chart configuration parameter |
| browser.image.tag | string | - | Chart configuration parameter |
| browser.image.digest | string | - | Chart configuration parameter |
| browser.image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| browser.resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| browser.resources.requests.memory | stringnumber | - | Chart configuration parameter |
| browser.resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| browser.resources.limits.memory | stringnumber | - | Chart configuration parameter |
| browser.securityContext.runAsUser | integer | 1000 | Chart configuration parameter |
| browser.securityContext.runAsGroup | integer | 1000 | Chart configuration parameter |
| browser.securityContext.runAsNonRoot | boolean | true | Chart configuration parameter |
| browser.securityContext.allowPrivilegeEscalation | boolean | false | Chart configuration parameter |
| browser.securityContext.capabilities.drop | array | ["ALL"] | 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(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gateway.enabled | boolean | false | Chart configuration parameter |
| gateway.annotations | object | - | Chart configuration parameter |
| gateway.parentRefs | array | - | Chart configuration parameter |
| gateway.hostnames | array | - | Chart configuration parameter |
| gateway.path | string | / | Chart configuration parameter |
| gateway.pathType | string | PathPrefix | Chart configuration parameter |
External Secrets(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | false | Chart configuration parameter |
| externalSecrets.apiVersion | string | external-secrets.io/v1 | Chart configuration parameter |
| externalSecrets.refreshInterval | string | 1h | Chart configuration parameter |
| externalSecrets.secretStoreRef.name | string | "" | Chart configuration parameter |
| externalSecrets.secretStoreRef.kind | string | SecretStore | Chart configuration parameter |
| externalSecrets.target.name | string | "" | Chart configuration parameter |
| externalSecrets.target.creationPolicy | string | Owner | Chart configuration parameter |
| externalSecrets.data | array | - | Chart configuration parameter |
| externalSecrets.dataFrom | array | - | 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(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| resources.requests.memory | stringnumber | - | Chart configuration parameter |
| resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| resources.limits.memory | stringnumber | - | Chart configuration parameter |
Pod Security(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.fsGroup | integer | 1000 | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | string | OnRootMismatch | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | string | RuntimeDefault | Chart configuration parameter Allowed: RuntimeDefaultLocalhostUnconfined |
| podSecurityContext.seccompProfile.localhostProfile | string | - | Chart configuration parameter |
Container Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.runAsUser | integer | 1000 | Chart configuration parameter |
| securityContext.runAsGroup | integer | 1000 | Chart configuration parameter |
| securityContext.runAsNonRoot | boolean | true | Chart configuration parameter |
| securityContext.allowPrivilegeEscalation | boolean | false | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | false | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.capabilities.add | 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 |
No schema parameters match your search
Try searching for a different keyword or reset the filter.