Skip to content
Klutch.sh Docs

Deploying a ChangeDetection App

Introduction

ChangeDetection.io is a powerful open-source self-hosted website change detection and monitoring platform that helps you track changes on any website. Whether you’re monitoring competitor pricing, job postings, product availability, news updates, or any web content changes, ChangeDetection.io provides intelligent monitoring with visual diff comparisons, customizable notifications, and flexible detection rules. With support for JavaScript rendering, XPath selectors, CSS filters, and webhook integrations, it’s the perfect solution for automated website monitoring and alerting.

Deploying ChangeDetection on Klutch.sh provides a production-ready, scalable infrastructure for your website monitoring needs with automated Docker deployments, persistent storage for your watch lists and history, secure environment variable management, and reliable uptime for continuous monitoring. Whether you’re tracking single websites or managing hundreds of monitors, Klutch.sh simplifies the deployment process and ensures your ChangeDetection instance is always available to catch important changes.

This comprehensive guide walks you through deploying ChangeDetection.io on Klutch.sh using a Dockerfile, configuring persistent volumes for data retention, setting up environment variables for notifications and integrations, and implementing production best practices for reliable website change monitoring at scale.

Prerequisites

Before you begin deploying ChangeDetection on Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your ChangeDetection deployment configuration
  • Basic understanding of Docker containers and environment variables
  • (Optional) API keys for notification services (email, Slack, Discord, Telegram, etc.)
  • Access to the Klutch.sh dashboard

Understanding ChangeDetection Architecture

ChangeDetection consists of several key components:

  • Python Backend: Flask-based application handling monitoring logic and API endpoints
  • Web UI: Browser-based interface for managing monitors and viewing changes
  • Storage: Local filesystem storage for watch configurations, snapshots, and change history
  • Background Workers: Automated monitoring tasks running on configurable schedules
  • Browser Rendering: Optional Playwright/Chrome integration for JavaScript-heavy websites

When deployed on Klutch.sh, ChangeDetection automatically detects your Dockerfile and builds a container image. The platform manages traffic routing via HTTP, provides SSL certificates automatically, and offers persistent storage options to preserve your monitoring data across deployments.

Project Structure

A minimal repository structure for deploying ChangeDetection on Klutch.sh:

changedetection-deployment/
├── Dockerfile
├── .dockerignore
├── .gitignore
└── README.md

This simple structure allows Klutch.sh to automatically detect and build your ChangeDetection container. You don’t need to include application code since ChangeDetection comes pre-packaged in the official Docker image.

Creating Your Dockerfile

Klutch.sh automatically detects a Dockerfile in the root directory of your repository. Create a Dockerfile that uses the official ChangeDetection image as the base:

FROM ghcr.io/dgtlmoon/changedetection.io:latest


# Expose the default ChangeDetection port
EXPOSE 5000


# The official image includes an entrypoint
# that handles initialization

Option 2: Dockerfile with Playwright Support (JavaScript Rendering)

For monitoring websites that require JavaScript rendering:

FROM ghcr.io/dgtlmoon/changedetection.io:latest


# Install Playwright dependencies for JavaScript rendering
USER root
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    && rm -rf /var/lib/apt/lists/*


# Install Playwright browsers
RUN playwright install --with-deps chromium


USER nobody


# Expose the application port
EXPOSE 5000

Option 3: Production Dockerfile with Health Checks

FROM ghcr.io/dgtlmoon/changedetection.io:latest


# Set working directory
WORKDIR /datastore


# Install health check dependencies
USER root
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
USER nobody


# Expose the application port
EXPOSE 5000


# Add health check for monitoring
HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:5000/ || exit 1

Important Notes:

  • ChangeDetection’s official image listens on port 5000 internally
  • Klutch.sh will route external HTTP traffic to port 5000 in your container
  • The /datastore directory is where ChangeDetection stores all monitoring data
  • For JavaScript rendering, ensure sufficient memory allocation (2GB+ recommended)

Deploying to Klutch.sh

  1. Create Your Repository

    Create a new GitHub repository and add your Dockerfile:

    Terminal window
    mkdir changedetection-deployment
    cd changedetection-deployment
    

    # Create Dockerfile
    cat > Dockerfile << 'EOF'
    FROM ghcr.io/dgtlmoon/changedetection.io:latest
    

    EXPOSE 5000
    

    HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
      CMD curl -f http://localhost:5000/ || exit 1
    EOF
    

    # Create .gitignore
    cat > .gitignore << 'EOF'
    datastore/
    .env
    .DS_Store
    EOF
    

    # Initialize git and push
    git init
    git add .
    git commit -m "Initial ChangeDetection deployment setup"
    git remote add origin https://github.com/YOUR_USERNAME/changedetection-deployment.git
    git push -u origin main

  2. Access the Klutch.sh Dashboard

    Navigate to klutch.sh/app and log in to your account.

  3. Create a New Project

    • Click “New Project” in the dashboard
    • Enter a project name (e.g., “Website Monitoring”)
    • Select your preferred region for deployment

  4. Create a New Application

    • Within your project, click “New App”
    • Name your application (e.g., “ChangeDetection”)
    • Connect your GitHub repository containing the Dockerfile

  5. Configure Build Settings

    Klutch.sh automatically detects the Dockerfile in your repository root and builds your application using Docker.

  6. Configure Traffic Settings

    In the app settings:

    • Select HTTP as the traffic type
    • The internal port is automatically set to 5000 (ChangeDetection’s default port)
    • Klutch.sh will route external traffic to this port

  7. Set Up Persistent Storage

    ChangeDetection requires persistent storage to retain watch lists, snapshots, and monitoring history across deployments:

    • In the app settings, navigate to the “Volumes” section
    • Click “Add Volume”
    • Set the mount path to /datastore
    • Set the volume size (recommended: 5GB minimum, 20GB+ for extensive monitoring)
    • Click “Add” to attach the volume

    Critical: The /datastore directory stores:

    • Watch configurations and URLs
    • Change history and snapshots
    • Visual diff images
    • Notification settings
    • User preferences

  8. Configure Environment Variables

    In the app settings, add optional environment variables for customization:

    Authentication (Recommended for Production):

    Terminal window
    WEBDRIVER_URL=http://localhost:4444/wd/hub
    USE_X_SETTINGS=1

    Base URL Configuration:

    Terminal window
    BASE_URL=https://example-app.klutch.sh

    Notification Settings (Optional):

    For Email notifications:

    Terminal window
    NOTIFICATION_MAIL_SERVER_HOSTNAME=smtp.gmail.com
    NOTIFICATION_MAIL_SERVER_PORT=587
    NOTIFICATION_MAIL_FROM=alerts@yourdomain.com
    NOTIFICATION_MAIL_SERVER_USER=your-email@gmail.com
    NOTIFICATION_MAIL_SERVER_PASS=your-app-password

    For Webhook notifications:

    Terminal window
    NOTIFICATION_WEBHOOK_URL=https://your-webhook-endpoint.com/alerts

    Performance Tuning:

    Terminal window
    MINIMUM_SECONDS_RECHECK_TIME=60
    FETCH_WORKERS=4

  9. Deploy Your Application

    • Review all settings
    • Click “Deploy” or “Create”
    • Klutch.sh will build the Docker image from your Dockerfile
    • Monitor the build logs in the dashboard
    • Once deployed, your ChangeDetection instance will be accessible at the provided URL

  10. Access Your ChangeDetection Instance

    After deployment completes:

    • Visit your app URL (e.g., https://example-app.klutch.sh)
    • Complete the initial setup wizard if prompted
    • Start adding websites to monitor

Getting Started with ChangeDetection

Once your ChangeDetection instance is deployed, here’s how to create your first website monitor:

Creating Your First Monitor

  1. Access the Web Interface

    Navigate to your ChangeDetection URL (e.g., https://example-app.klutch.sh)

  2. Add a New Watch

    Click “Add new” or the ”+” button to create a monitor:

    URL to Monitor: https://example.com/products

  3. Configure Detection Settings

    • Check Frequency: Set how often to check (e.g., every 6 hours)
    • Filters: Use CSS selectors or XPath to monitor specific elements
    • Trigger Text: Set keywords that trigger notifications

  4. Set Up Notifications

    Configure alerts for when changes are detected:

    • Email notifications
    • Webhook calls
    • Discord/Slack integration
    • Custom notification formats

Example: Monitoring a Price Change

Here’s a practical example monitoring a product price:

URL: https://store.example.com/product/laptop
CSS Filter: .price-container .current-price
Notification: Email + Webhook
Check Interval: Every 2 hours

ChangeDetection will:

  • Check the price every 2 hours
  • Detect any changes in the price element
  • Send notifications when the price changes
  • Store visual diffs showing before/after

Advanced Monitoring with XPath

For complex pages, use XPath selectors:

//div[@class='price-container']/span[@class='current-price']/text()

This extracts only the price text for precise monitoring.

Environment Variables Reference

Complete list of useful environment variables for ChangeDetection:

Core Settings

Terminal window
# Base URL for ChangeDetection
BASE_URL=https://example-app.klutch.sh


# Enable/disable features
HIDE_REFERER=true
FETCH_WORKERS=4

Email Notifications

Terminal window
NOTIFICATION_MAIL_SERVER_HOSTNAME=smtp.gmail.com
NOTIFICATION_MAIL_SERVER_PORT=587
NOTIFICATION_MAIL_SERVER_USER=alerts@yourdomain.com
NOTIFICATION_MAIL_SERVER_PASS=your-secure-password
NOTIFICATION_MAIL_FROM=changedetection@yourdomain.com
NOTIFICATION_MAIL_TLS=true

Webhook Notifications

Terminal window
NOTIFICATION_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Performance Tuning

Terminal window
# Minimum time between checks (seconds)
MINIMUM_SECONDS_RECHECK_TIME=60


# Number of concurrent fetch workers
FETCH_WORKERS=4


# Request timeout (seconds)
DEFAULT_FETCH_TIMEOUT=30

Security Settings

Terminal window
# Enable password protection (set in UI after first login)
USE_X_SETTINGS=1

Set these in the Klutch.sh dashboard under Environment Variables. Mark sensitive values (passwords, API keys) as secrets.

Persistent Storage and Data Management

Storage Layout

ChangeDetection stores all data in /datastore:

/datastore/
├── url-watches/          # Individual watch configurations
├── snapshots/            # Change history and snapshots
├── notifications/        # Notification settings
└── settings/             # Global application settings

Backup Recommendations

Regularly backup your /datastore volume:

  1. Automated Backups: Configure scheduled backups of the persistent volume
  2. Export Watches: Use ChangeDetection’s export feature to save configurations
  3. Snapshot History: Consider archiving old snapshots to reduce storage usage

Storage Sizing Guide

  • Light Usage (1-20 monitors): 5GB
  • Medium Usage (20-100 monitors): 10-20GB
  • Heavy Usage (100+ monitors): 20GB+
  • With Visual Diffs: Add 50-100% more storage

Production Best Practices

Security

  1. Enable Authentication

    • Set up password protection immediately after first login
    • Use strong, unique passwords
    • Consider placing behind a VPN or IP whitelist for sensitive monitoring

  2. Secure Notifications

    • Use HTTPS webhooks
    • Store API keys and credentials as Klutch.sh secrets
    • Enable TLS for email notifications

  3. Regular Updates

    • Keep ChangeDetection updated to the latest version
    • Monitor the GitHub repository for security updates
    • Update your Dockerfile to pin specific versions for stability

Performance Optimization

  1. Resource Allocation

    • Allocate at least 1GB RAM for basic monitoring
    • Use 2GB+ RAM if enabling JavaScript rendering
    • Scale CPU resources based on number of concurrent checks

  2. Check Frequency Optimization

    • Don’t check too frequently (respect target sites)
    • Use reasonable intervals (1-6 hours for most cases)
    • Stagger check times for multiple monitors

  3. Efficient Filtering

    • Use specific CSS selectors to monitor only relevant content
    • Exclude dynamic elements (timestamps, ads, counters)
    • Minimize the amount of content being monitored

Monitoring and Maintenance

  1. Health Checks

    • Monitor ChangeDetection’s availability via health endpoint
    • Set up alerts if the service becomes unavailable
    • Review logs regularly for errors or issues

  2. Data Retention

    • Archive old snapshots periodically
    • Clean up completed or obsolete monitors
    • Monitor storage usage and expand volumes as needed

  3. Notification Testing

    • Regularly test notification channels
    • Verify webhooks are reachable
    • Confirm email delivery

Troubleshooting

Common Issues and Solutions

ChangeDetection returns 502/503 errors

Solution:

  • Verify the container is running and healthy
  • Check that port 5000 is correctly configured
  • Review container logs for startup errors
  • Ensure sufficient memory allocation (1GB minimum)

Data not persisting between deployments

Solution:

  • Verify persistent volume is attached to /datastore
  • Check volume mount path is exactly /datastore
  • Confirm volume has sufficient storage space
  • Review file permissions (container runs as nobody user)

JavaScript-heavy sites not being monitored correctly

Solution:

  • Use the Dockerfile with Playwright support
  • Increase memory allocation to 2GB+
  • Enable JavaScript rendering in the watch settings
  • Consider using a dedicated WebDriver container

Notifications not being sent

Solution:

  • Verify email/webhook credentials in environment variables
  • Test notification channels from ChangeDetection UI
  • Check firewall rules allow outbound SMTP/HTTPS traffic
  • Review notification logs for error messages

High CPU or memory usage

Solution:

  • Reduce number of concurrent workers (FETCH_WORKERS)
  • Increase check intervals for monitors
  • Disable JavaScript rendering if not needed
  • Use more specific CSS selectors to reduce processing

Debug Commands

Access container logs via Klutch.sh dashboard or use these debug approaches:

Terminal window
# Check application logs
tail -f /datastore/changedetection.log


# Verify storage mount
ls -la /datastore/


# Test network connectivity
curl -I https://example.com


# Check resource usage
top -b -n 1

Advanced Configuration

Using with Playwright for JavaScript Rendering

For sites requiring JavaScript:

  1. Deploy with the Playwright-enabled Dockerfile

  2. Configure environment variable:

    Terminal window
    PLAYWRIGHT_DRIVER_URL=ws://localhost:3000

  3. Increase memory allocation to 2GB+

  4. Enable “Use Chrome/Chromium” in watch settings

Integration with External Services

Slack Integration:

Terminal window
NOTIFICATION_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

Discord Integration:

Terminal window
NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK

Custom Webhook Format: Configure JSON payload format in ChangeDetection UI for custom integrations.

API Access

ChangeDetection provides a REST API for automation:

Terminal window
# Get all watches
curl https://example-app.klutch.sh/api/v1/watch


# Add new watch programmatically
curl -X POST https://example-app.klutch.sh/api/v1/watch \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "tag": "price-monitoring"}'

Scaling Considerations

As your monitoring needs grow:

  1. Vertical Scaling

    • Increase CPU/RAM allocation in Klutch.sh
    • Recommended: 2 vCPU, 4GB RAM for 100+ monitors

  2. Storage Scaling

    • Expand persistent volume size as needed
    • Archive old snapshots to external storage
    • Consider implementing data retention policies

  3. Multiple Instances

    • Deploy separate instances for different teams/projects
    • Use tags to organize monitors within instances
    • Consider dedicated instances for high-frequency monitoring

Migration and Data Import

Importing from Another ChangeDetection Instance

  1. Export watches from source instance (JSON format)
  2. Copy exported file to your new deployment
  3. Use import feature in ChangeDetection UI
  4. Verify all watches and configurations

Migrating from Other Tools

ChangeDetection can replace:

  • Visualping
  • Distill Web Monitor
  • Wachete
  • Custom monitoring scripts

Export URLs and configuration, then recreate monitors in ChangeDetection.

Resources

Next Steps

After successfully deploying ChangeDetection on Klutch.sh:

  1. Add Your First Monitors: Start with 2-3 important websites to monitor
  2. Configure Notifications: Set up email or webhook alerts
  3. Test Detection: Make a manual change to verify detection works
  4. Optimize Settings: Adjust check frequencies based on your needs
  5. Scale Up: Add more monitors as you validate the deployment

For advanced monitoring scenarios, explore ChangeDetection’s filtering capabilities, API automation, and integration options with your existing tools and workflows.

Deploying ChangeDetection on Klutch.sh provides a reliable, scalable foundation for website monitoring, whether you’re tracking a handful of pages or managing hundreds of monitors across your organization.