Quick Start Guide

Get your first website monitor running in under 5 minutes

Overview

This guide will take you from zero to your first working monitor with notifications in just a few minutes. By the end, you’ll have changedetection.io monitoring a website and sending you alerts when changes occur.

Choose your path:

• Managed service: Sign up at changedetection.io for instant access ($8.99/month)
• Self-hosted: Follow the installation steps below for the free, open-source version

Installation

Choose the installation method that works best for you:

Docker (Recommended)

The fastest way to get started with changedetection.io:

docker run -d --restart always \
  -p "127.0.0.1:5000:5000" \
  -v datastore-volume:/datastore \
  --name changedetection.io \
  dgtlmoon/changedetection.io

Mac users: Use port 5050 instead to avoid conflicts with AirPlay:

docker run -d --restart always -p "127.0.0.1:5050:5000" ...

Docker Compose

For more control and easier configuration:

# Clone the repository
git clone https://github.com/dgtlmoon/changedetection.io.git
cd changedetection.io

# Start the service
docker compose up -d

The docker-compose.yml file includes:

• Main changedetection service
• Optional browser automation (Playwright/Selenium)
• Volume configuration
• Environment variables

Python pip

Install directly via pip:

# Install
pip3 install changedetection.io

# Run (specify data directory and port)
changedetection.io -d /path/to/datastore -p 5000

The data directory will store all your watches, history, and settings.

Verify Installation

Once running, access the web interface:

1. Open your browser

   Navigate to http://127.0.0.1:5000 (or http://127.0.0.1:5050 on Mac)

2. First-time setup

   You should see the changedetection.io dashboard. No registration required for self-hosted installations!

The default installation uses the :latest tag for stable releases. Use :dev for bleeding-edge features from the master branch.

Create Your First Watch

Now let’s set up your first website monitor:

1. Add a new watch

   Click the ”+ Watch” button or “Add” in the top navigation.

   Enter a URL to monitor, for example:

   https://example.com/products/special-item
   
2. Configure basic settings

   On the watch edit page, you can configure:

   Essential Settings:

   • URL: The webpage to monitor
   • Title: A friendly name for this watch (optional, auto-detected from page title)
   • Check Interval: How often to check for changes

   Quick Setup: For your first watch, leave most settings at default and click “Save”.

3. Run first check

   Back on the watch list:

   1. Find your newly created watch
   2. Click the “Check Now” button (play icon)
   3. Wait a few seconds for the first check to complete

   The first check establishes a baseline — future checks will compare against this snapshot.

4. View the results

   Click on your watch to view:

   • Current snapshot of the page
   • Extracted content
   • Check history
   • Detected changes (none yet on first run)

Add Content Filtering

Monitor only specific parts of a page to avoid false positives:

CSS Selectors (Simple)

Edit your watch and add CSS selectors to the “CSS/JSONPath/JQ Filter” field:

/* Monitor only price elements */
.price, .product-price

/* Monitor main content */
main article

/* Monitor specific ID */
#product-details

Use browser DevTools (F12) to inspect elements and copy selectors.

Visual Selector (Advanced)

If you have Playwright enabled:

1. Enable JavaScript fetcher

   In watch settings, set “Fetch Method” to use Playwright/browser steps.

2. Open Visual Selector

   Click the “Visual Selector” tab in the watch editor.

3. Select elements

   Click on page elements to highlight and select what you want to monitor. The tool will generate the appropriate selectors automatically.

Visual Selector requires a Playwright connection. Configure PLAYWRIGHT_DRIVER_URL in your environment or use the managed service.

XPath (Powerful)

For complex targeting, use XPath expressions:

<!-- Monitor specific table cells -->
//table[@class='pricing']//td[@class='price']

<!-- Monitor paragraphs containing specific text -->
//p[contains(text(), 'In Stock')]

<!-- Monitor elements with regex (LXML) -->
//div[re:test(@class, 'product-.*')]

Set Up Notifications

Get alerted when changes are detected:

1. Configure notification endpoint

   Edit your watch and scroll to the “Notifications” section.

   Add one or more notification URLs using the Apprise format:

   # Discord
   discord://webhook_id/webhook_token
   
   # Slack
   slack://TokenA/TokenB/TokenC/
   
   # Email (SMTP)
   mailto://user:[e-mail]?to=[e-mail]
   
   # Telegram
   tgram://bot_token/chat_id/
   
   # Microsoft Teams
   msteams://TokenA/TokenB/TokenC/
   
   # Custom webhook
   json://your-server.com/webhook
   

   You can add multiple notification URLs (one per line) to send alerts to multiple services.

2. Customize notification content (optional)

   Use Jinja2 templates to customize your alerts:

   Title:

   Price changed for {{watch.title|default(watch.url)}}
   

   Body:

   {{watch_url}} had a change detected!
   
   Last checked: {{current_timestamp}}
   
   Changes:
   {{diff}}
   

   Available variables:

   • {{watch_url}}: The monitored URL
   • {{watch.title}}: Watch title
   • {{diff}}: HTML/text diff of changes
   • {{current_timestamp}}: Check timestamp
   • {{preview_url}}: Link to view the change
3. Test notifications

   Click “Send test notification” to verify your configuration before saving.

Trigger Detection

Control when notifications are sent:

Trigger on Text

Only get notified when specific text appears:

In Stock
Available Now
Price: $99

Add these to the “Trigger/wait for text” field. Supports regex:

Price: \$[0-9]+\.[0-9]{2}
(Available|In Stock)

Block on Text

Prevent notifications if specific text is present:

Out of Stock
Sold Out
Temporarily Unavailable

Add to “Block change detection if text matches”.

Ignore Text

Exclude dynamic content from change detection:

Last updated:
Copyright ©
View count:

Lines matching these patterns will be ignored during comparison.

Advanced: Monitor Prices

For product monitoring, use the specialized restock processor:

1. Enable restock mode

   In watch settings, enable:

   “Re-stock & Price detection for single product pages”

2. Set price thresholds

   Configure optional price alerts:

   • Above price: Alert if price exceeds this amount
   • Below price: Alert if price drops below this amount
   • Percentage change: Alert on % price change
3. Monitor stock status

   The processor automatically extracts:

   • Product price from meta tags
   • Stock availability status
   • Product name and details

   View this data directly in the watch preview.

The restock processor extracts pricing data from standard e-commerce meta tags (schema.org, Open Graph) found on most product pages.

Schedule Monitoring

Control when checks run:

Check Interval

Set how often the page is checked:

• Every 5 minutes (frequent)
• Every hour (moderate)
• Once per day (light monitoring)
• Custom: Specify weeks, days, hours, minutes, seconds

Respect the target website’s resources. Avoid excessive checking that could be seen as abusive.

Time Scheduling

Limit checks to specific times:

Example: Business hours only

• Monday-Friday: 9:00 AM - 5:00 PM
• Timezone: Your local timezone

Example: Foreign news at 9 AM

• Daily: 9:00 AM
• Timezone: Target country timezone

Use the “Schedule” section in watch settings with quick presets for business hours or weekends.

Common Patterns

Monitor job postings

URL: https://company.com/careers
CSS Filter: .job-listing, .career-opportunity
Trigger Text: (Software|Engineer|Developer)
Check Interval: Every 6 hours

Track price drops

URL: https://store.com/product/item-id
Processor: Restock & Price detection
Below Price: 99.99
Notification: discord://...
Check Interval: Every 1 hour

Monitor API responses

URL: https://api.example.com/status
Filter: jq:.status.health
Trigger Text: "degraded|down"
Notification: slack://...
Check Interval: Every 5 minutes

Government announcements

URL: https://government.gov/announcements
CSS Filter: #press-releases article
Ignore Text: Last updated:, Copyright
Check Interval: Every 3 hours
Schedule: Business hours only

Next Steps

Visual Selector

Learn to precisely target page elements

Browser Steps

Automate login, clicks, and form fills

JSON Filtering

Monitor and filter JSON API responses

Proxy Setup

Route requests through proxies

Troubleshooting

Changes detected on every check

Problem: Dynamic content (timestamps, ads, counters) triggers false positives.

Solutions:

• Use CSS/XPath selectors to monitor only relevant content
• Add dynamic text to the “Ignore text” field
• Use the Visual Selector to exclude changing elements

Notifications not sending

Checklist:

• Test notification URL using “Send test notification” button
• Check notification URL format matches Apprise syntax
• Verify network connectivity to notification service
• Check changedetection.io logs for error messages

JavaScript-heavy sites not loading

Problem: Content loaded by JavaScript doesn’t appear.

Solution: Enable Playwright fetcher:

1. Uncomment browser service in docker-compose.yml
2. Set PLAYWRIGHT_DRIVER_URL environment variable
3. Change watch fetch method to “Playwright Chrome/Javascript”

Port 5000 already in use (Mac)

Problem: macOS AirPlay uses port 5000.

Solution: Use port 5050:

docker run ... -p "127.0.0.1:5050:5000" ...

---

Want more examples? Visit changedetection.io/tutorials for detailed how-to guides and real-world scenarios.