# Change Detection Monitoring

> Website change detection and monitoring with notifications and visual diff comparison.

- Category: Monitoring & Observability
- Difficulty: beginner
- Components: changedetection, playwright, nginx
- Tags: changedetection, monitoring, web, alerts, diff
- Source: https://docker.recipes/monitoring/changedetection-io

## Overview

ChangeDetection.io is an open-source web monitoring service that tracks changes on websites and sends notifications when modifications are detected. Originally developed to fill the gap left when services like FollowThatPage became unreliable, ChangeDetection provides a self-hosted solution for monitoring product prices, job listings, news articles, or any web content that matters to you. The service supports visual diff comparisons, CSS/XPath selectors for precise monitoring, and integrates with numerous notification services including email, Slack, Discord, and webhooks. This stack combines ChangeDetection with Playwright browser automation and NGINX reverse proxy to create a robust monitoring platform. Playwright provides the JavaScript rendering capabilities needed to monitor modern single-page applications and dynamic content that traditional scrapers miss, while NGINX handles SSL termination, caching, and provides professional web server capabilities for production deployments. The architecture separates concerns effectively, with ChangeDetection handling the monitoring logic, Playwright managing browser automation in an isolated container, and NGINX providing enterprise-grade web serving. This combination is ideal for businesses needing reliable change monitoring, compliance teams tracking regulatory updates, e-commerce professionals monitoring competitor pricing, and IT teams keeping watch on service status pages. The stack provides both the technical capabilities needed for complex monitoring scenarios and the operational features required for production use, including proper logging, health checks, and scalable browser resource management.

## Features

- Visual diff comparison with screenshot capture showing exactly what changed on monitored pages
- JavaScript rendering support through Playwright integration for monitoring SPAs and dynamic content
- CSS selector and XPath filtering to monitor specific page elements rather than entire pages
- Concurrent browser process management with configurable limits to control resource usage
- Multiple notification channels including webhooks, email, Slack, Discord, and custom integrations
- Configurable screen resolution and color depth for consistent screenshot comparison across monitoring cycles
- JSON and text change detection with custom extraction rules for API endpoints and structured data
- Proxy support through NGINX for SSL termination, caching, and professional deployment scenarios

## Use cases

- E-commerce price monitoring to track competitor pricing changes and product availability
- Job board monitoring for new postings matching specific criteria or locations
- Regulatory compliance monitoring to track changes in government websites and policy documents
- Software release monitoring to detect new versions and security updates for critical applications
- News and content monitoring for journalists and researchers tracking specific topics or sources
- Service status page monitoring to detect outages and maintenance announcements from vendors
- Real estate listing monitoring for new properties matching specific criteria in target markets

## Prerequisites

- Minimum 2GB RAM recommended due to Playwright browser processes and concurrent monitoring tasks
- Docker and Docker Compose installed with support for multi-container networking
- Ports 80, 443, and 5000 available on the host system for web access and API endpoints
- Basic understanding of CSS selectors or XPath for configuring precise element monitoring
- SMTP server configuration or webhook endpoints ready for notification delivery
- SSL certificates prepared if deploying with HTTPS support through NGINX

## docker-compose.yml

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

  playwright:
    image: dgtlmoon/sockpuppetbrowser:latest
    environment:
      SCREEN_WIDTH: 1920
      SCREEN_HEIGHT: 1080
      SCREEN_DEPTH: 24
      MAX_CONCURRENT_CHROME_PROCESSES: 10
    networks:
      - changedetection-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - changedetection
    networks:
      - changedetection-net
    restart: unless-stopped

volumes:
  changedetection_data:

networks:
  changedetection-net:
    driver: bridge
```

## .env

```bash
# Base URL (for notifications)
BASE_URL=https://change.example.com
```

## Usage notes

- Web UI at http://localhost:5000
- Add URLs to monitor
- Visual diff comparison
- Supports CSS/XPath selectors

## Troubleshooting

- ChangeDetection shows 'Browser connection failed': Verify playwright container is running and PLAYWRIGHT_DRIVER_URL environment variable points to ws://playwright:3000
- Screenshots appear blank or incomplete: Increase SCREEN_WIDTH and SCREEN_HEIGHT environment variables in playwright service, or adjust page load timeout settings
- High memory usage from browser processes: Reduce MAX_CONCURRENT_CHROME_PROCESSES setting in playwright container or implement monitoring schedules to spread load
- Monitoring fails on JavaScript-heavy sites: Ensure Playwright integration is enabled in ChangeDetection settings and increase page render wait time
- NGINX proxy errors to ChangeDetection: Check that changedetection service is healthy and accessible on port 5000 within the Docker network
- Persistent data loss after container restart: Verify changedetection_data volume is properly mounted and has correct permissions for the container user

