# Change Detection Monitor

> Web page change detection with notifications.

- Category: Home Lab & Self-Hosting
- Difficulty: beginner
- Components: changedetection, playwright, ntfy
- Tags: monitoring, web, notifications, alerts
- Source: https://docker.recipes/homelab/changedetection-stack

## Overview

ChangeDetection.io is an open-source web monitoring tool that tracks changes on websites and web applications, alerting users when content modifications occur. Originally developed as a self-hosted alternative to commercial monitoring services, it provides granular control over what gets monitored, from entire pages to specific CSS selectors, with support for complex filtering and change detection algorithms that can ignore cosmetic updates while catching meaningful content changes.

This monitoring stack combines ChangeDetection.io with Playwright browser automation and ntfy notification service to create a comprehensive change detection system. The Playwright component handles JavaScript-heavy sites and complex rendering scenarios that simple HTTP requests cannot capture, while ntfy provides a lightweight, self-hosted notification server that can deliver alerts through multiple channels including mobile push notifications, webhooks, and email integration.

Homelab enthusiasts and small teams will find this stack particularly valuable for monitoring price changes, service status pages, job postings, or any web content that requires immediate attention when updated. The combination eliminates dependencies on external services while providing enterprise-grade monitoring capabilities that can scale from monitoring a handful of personal sites to hundreds of business-critical web resources.

## Features

- CSS selector-based monitoring for precise element tracking and change detection
- Playwright browser engine integration for full JavaScript rendering and SPA support
- Visual diff detection with screenshot comparison and highlighted change regions
- XPath and JSONPath filtering for structured data monitoring and API endpoint changes
- Regex pattern matching for content filtering and false positive reduction
- Self-hosted ntfy notification server with topic-based message routing
- Change detection threshold configuration to ignore minor cosmetic updates
- Built-in proxy support through Playwright for geo-restricted content monitoring

## Use cases

- E-commerce price monitoring for competitor analysis and deal alerting
- Government website monitoring for permit applications and regulatory updates
- Job board monitoring for specific positions or company postings
- Service status page monitoring for third-party dependencies and SaaS providers
- Real estate listing monitoring for new properties in specific areas or price ranges
- News website monitoring for breaking news in specific categories or topics
- Software release monitoring for GitHub releases and changelog updates

## Prerequisites

- Docker host with minimum 2GB RAM for Playwright browser instances
- Available ports 5000 and 8080 for web interface access
- Persistent storage allocation for change detection history and notification cache
- Network connectivity to target websites and any notification endpoints
- Basic understanding of CSS selectors for advanced monitoring configuration
- Mobile device or webhook endpoint configured for ntfy notifications

## docker-compose.yml

```yaml
services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io:latest
    container_name: changedetection
    restart: unless-stopped
    ports:
      - "${CD_PORT:-5000}:5000"
    environment:
      - PLAYWRIGHT_DRIVER_URL=ws://playwright:3000
      - BASE_URL=http://localhost:${CD_PORT:-5000}
    volumes:
      - changedetection_data:/datastore
    depends_on:
      - playwright

  playwright:
    image: browserless/chrome:latest
    container_name: cd-playwright
    restart: unless-stopped
    environment:
      - DEFAULT_BLOCK_ADS=true
      - DEFAULT_STEALTH=true

  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: cd-ntfy
    restart: unless-stopped
    ports:
      - "${NTFY_PORT:-8080}:80"
    volumes:
      - ntfy_cache:/var/cache/ntfy

volumes:
  changedetection_data:
  ntfy_cache:
```

## .env

```bash
# Change Detection
CD_PORT=5000
NTFY_PORT=8080
```

## Usage notes

- Change Detection at http://localhost:5000
- Ntfy at http://localhost:8080
- Add URLs to monitor
- Playwright for JS rendering

## Troubleshooting

- ChangeDetection shows 'Playwright connection failed': Verify playwright container is running and check PLAYWRIGHT_DRIVER_URL environment variable matches service name
- Memory errors in Playwright container: Increase Docker memory limits or reduce concurrent monitoring jobs in ChangeDetection settings
- ntfy notifications not received: Check ntfy topic subscription on client device and verify container port mapping for external access
- JavaScript-heavy sites not detecting changes: Enable Playwright renderer in monitor settings and increase page load wait time
- False positive change alerts: Implement CSS filters to exclude dynamic elements like timestamps, ads, or user counters
- ChangeDetection data loss after restart: Verify changedetection_data volume is properly mounted and has write permissions

