changedetection.io on AWS User Guide

Overview

This image runs changedetection.io, the self-hosted service that monitors web pages for changes and notifies you when something you care about is added, removed or updated. You point it at any URL, optionally narrow it to a CSS or xpath region, and it re-fetches the page on a schedule, stores a snapshot, and shows you a clear visual diff of exactly what changed.

changedetection.io runs as a container bound to 127.0.0.1:5000 on the loopback interface and is fronted by nginx as a reverse proxy on port 80 (and 443 once you add TLS), with the WebSocket upgrade its live-updating watch list needs already configured. All settings, page-content history snapshots and diffs live on a dedicated EBS data volume mounted at /var/lib/changedetection, independently resizable and separate from the operating system disk.

On the first boot of every deployed instance, a one-shot service generates a per-instance access password, applies it to changedetection.io using the application's own salted hash, verifies the sign-in round-trip, and records the password in /root/changedetection-credentials.txt with mode 0600. No shared or default credentials ship in the image, and you can change or remove the password later from the settings screen.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your operators will reach changedetection.io on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for changedetection.io. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger; the image adds a separate data volume for the watch database automatically.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg changedetection.io Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=changedetection-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Access Password

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/changedetection-credentials.txt

You will see a plain text file containing the changedetection.io URL and the per-instance access password (there is no username). From the same SSH session you can confirm the deployment is healthy; the health endpoint is open and served by nginx:

curl -fsS http://127.0.0.1/healthz

ok

An ok response confirms nginx is fronting the application. You can also confirm the services that make up the stack are running, and that the changedetection.io container is up:

systemctl is-active docker nginx changedetection-firstboot
sudo docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

active
active
active
NAMES             IMAGE                                        STATUS
changedetection   ghcr.io/dgtlmoon/changedetection.io:0.55.7   Up 3 minutes

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. changedetection.io presents its sign-in page and prompts for the access password.

The changedetection.io sign-in page, served on first boot behind nginx. Sign in with the per-instance access password.

Enter the password from /root/changedetection-credentials.txt and select Login. changedetection.io opens on the watch list, which shows the pages it is monitoring, when each was last checked, and whether a change has been detected. Two sample watches are seeded so you have a populated list to explore.

The watch list, showing each monitored page with its last-checked time, change status, and the recheck, edit and preview controls.

Step 5: Add a Watch

To monitor a new page, paste its URL into the Add a new web page change detection watch box at the top of the watch list, optionally add a Group tag to organise related watches, choose whether to track general text and HTML changes or restock and price changes, and select Watch. Use Edit > Watch instead if you want to set the check interval, restrict monitoring to a page region, or configure notifications before the first check.

Adding a new watch by pasting a URL and tagging it, ready for changedetection.io to check the page on a schedule and diff it when it changes.

changedetection.io fetches the page immediately, stores the first snapshot, and then re-checks it on the schedule you set. To narrow a watch to just the part of a page you care about, open the watch's Edit screen and use the Visual Selector, or enter a CSS selector or xpath under Filters & Triggers, so navigation menus and adverts do not create noise.

Step 6: Read a Change Diff

When changedetection.io detects a change, the watch is highlighted on the list and its Last Changed time updates. Select the watch, or its Diff control, to open the difference view. The diff view lets you pick any two stored versions with the From and To selectors and highlights exactly what changed: removed text in red and added text in green. You can switch between word-level and line-level comparison and toggle which change types are shown.

The visual diff view comparing two stored versions of a monitored page, highlighting removed content in red and added content in green.

Step 7: Configure Notifications

changedetection.io can notify you the moment a change is detected through dozens of channels. Open Settings → Notifications to set a default notification for every watch, or open an individual watch's Edit → Notifications tab to set one per watch. Notification targets use the Apprise URL format, so you can send to email, a webhook, Slack, Discord, Telegram and many more. A typical email target looks like mailto://user:pass@smtp.example.com and a webhook target looks like json://your-endpoint.example.com/hook. The notification body is templated from the change, so you can include the watch URL, the diff and the current snapshot. Use Send test notification to confirm the channel before relying on it.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve changedetection.io over HTTPS so your session and the WebSocket the live watch list uses cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d changedetection.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot obtains a certificate and rewrites the nginx server block to serve HTTPS and redirect HTTP; the WebSocket upgrade headers already in the site are preserved. Renewal is handled automatically by the certbot systemd timer. After enabling TLS, set the base URL used in notification links to your HTTPS address by adding -e BASE_URL=https://changedetection.your-domain.example/ when the container is recreated, or set it under the application settings.

Step 9: Backups and Maintenance

changedetection.io keeps its settings, watch configuration and page-content history under /var/lib/changedetection on the dedicated data volume, confirmed here on its own disk:

df -h /var/lib/changedetection | tail -1

/dev/nvme1n1     20G  252K   19G   1% /var/lib/changedetection

Because that is a separate EBS volume you can take a coordinated EBS snapshot of it for point-in-time backups, or archive the tree to object storage:

sudo docker stop changedetection
sudo tar czf <backup-dir>/changedetection-$(date +%F).tgz -C /var/lib changedetection
sudo docker start changedetection

Ship the archive to an Amazon S3 bucket or another object store. To change or remove the access password, sign in and use Settings → General → Password. The reverse proxy and engine run under systemd and the changedetection.io container runs with a restart policy of always; check their state at any time:

systemctl is-active docker nginx
sudo docker ps --filter name=changedetection

Step 10: Scaling and Operations

• Increase the check frequency and the number of watches to suit your workload; changedetection.io processes checks in the background so the UI stays responsive
• Add optional JS-rendering by running a browser sidecar (for example a Playwright or sockpuppetbrowser container) and pointing watches at it, for pages that need JavaScript to render
• Put the web tier behind an Application Load Balancer and terminate TLS there; forward the WebSocket upgrade so the live watch list connects
• Grow the data volume by extending the EBS data volume and running sudo resize2fs on /var/lib/changedetection
• Use Group tags and per-tag notification settings to organise large numbers of watches by team or purpose
• Pin the changedetection.io version for a fleet by controlling which AMI version you launch

The official changedetection.io documentation is available at https://changedetection.io/docs.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general changedetection.io questions consult the documentation at https://changedetection.io/docs. changedetection.io is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.