Docker Compose Installation

Docker Compose provides the easiest way to run changedetection.io with optional browser automation support for JavaScript-heavy websites.

Quick Start

Clone or download the repository

git clone https://github.com/dgtlmoon/changedetection.io.git
cd changedetection.io

Alternatively, download just the docker-compose.yml file from the repository.

Start the service

docker compose up -d

Access the web interface

Open your browser and navigate to:

http://127.0.0.1:5000

Basic Configuration

The default docker-compose.yml provides a minimal setup:

docker-compose.yml

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    hostname: changedetection
    volumes:
      - changedetection-data:/datastore
    ports:
      - 127.0.0.1:5000:5000
    restart: unless-stopped

volumes:
  changedetection-data:

Mac users should change the port mapping to 127.0.0.1:5050:5000 to avoid conflicts with Airplay.

Environment Variables

Uncomment and configure environment variables in your docker-compose.yml:

docker-compose.yml

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    hostname: changedetection
    volumes:
      - changedetection-data:/datastore
    environment:
      - PORT=5000
      - LOGGER_LEVEL=INFO
      - BASE_URL=https://mysite.com
      - FETCH_WORKERS=10
      - MINIMUM_SECONDS_RECHECK_TIME=3
      - TZ=America/Los_Angeles
    ports:
      - 127.0.0.1:5000:5000
    restart: unless-stopped

volumes:
  changedetection-data:

Key Environment Variables

Variable	Default	Description
`PORT`	`5000`	Web interface listening port
`LOGGER_LEVEL`	`DEBUG`	TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
`BASE_URL`	-	Base URL for notification links
`FETCH_WORKERS`	`10`	Number of concurrent fetchers
`MINIMUM_SECONDS_RECHECK_TIME`	`3`	Minimum recheck interval (0 to disable)
`TZ`	-	Timezone for scheduling (e.g., `America/Los_Angeles`)
`LC_ALL`	`en_US.UTF-8`	Text processing locale
`DISABLE_VERSION_CHECK`	`false`	Disable version check/telemetry
`HIDE_REFERER`	`false`	Hide referer header from monitored sites

Reverse Proxy Configuration

environment:
  - USE_X_SETTINGS=1
  - BASE_URL=https://mysite.com

When using a reverse proxy, set USE_X_SETTINGS=1 to respect X-Forwarded-Prefix and similar headers.

Proxy Configuration

environment:
  - HTTP_PROXY=socks5h://10.10.1.10:1080
  - HTTPS_PROXY=socks5h://10.10.1.10:1080
  - NO_PROXY="localhost,192.168.0.0/24"

Plugin Installation

environment:
  - EXTRA_PACKAGES=changedetection.io-osint-processor

For multiple plugins, separate with spaces:

environment:
  - EXTRA_PACKAGES=changedetection.io-osint-processor another-plugin

Browser Automation Setup

For JavaScript-heavy websites, add browser automation using Playwright (recommended) or Selenium.

Option 1: Playwright with Sockpuppet Browser (Recommended)

docker-compose.yml

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    hostname: changedetection
    volumes:
      - changedetection-data:/datastore
    environment:
      - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000
    ports:
      - 127.0.0.1:5000:5000
    restart: unless-stopped
    depends_on:
      browser-sockpuppet-chrome:
        condition: service_started

  browser-sockpuppet-chrome:
    hostname: browser-sockpuppet-chrome
    image: dgtlmoon/sockpuppetbrowser:latest
    cap_add:
      - SYS_ADMIN
    restart: unless-stopped
    environment:
      - SCREEN_WIDTH=1920
      - SCREEN_HEIGHT=1024
      - SCREEN_DEPTH=16
      - MAX_CONCURRENT_CHROME_PROCESSES=10

volumes:
  changedetection-data:

Sockpuppet Browser provides the best performance and supports full-page screenshots and the Visual Selector feature.

The SYS_ADMIN capability is required for Chrome to run in some environments. See the Puppeteer troubleshooting guide for alternatives.

Option 2: Selenium WebDriver (Legacy)

docker-compose.yml

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    hostname: changedetection
    volumes:
      - changedetection-data:/datastore
    environment:
      - WEBDRIVER_URL=http://browser-selenium-chrome:4444/wd/hub
    ports:
      - 127.0.0.1:5000:5000
    restart: unless-stopped
    depends_on:
      browser-selenium-chrome:
        condition: service_started

  browser-selenium-chrome:
    hostname: browser-selenium-chrome
    image: selenium/standalone-chrome:4
    environment:
      - VNC_NO_PASSWORD=1
      - SCREEN_WIDTH=1920
      - SCREEN_HEIGHT=1080
      - SCREEN_DEPTH=24
    volumes:
      - /dev/shm:/dev/shm
    restart: unless-stopped

volumes:
  changedetection-data:

Selenium WebDriver is deprecated and doesn’t support full-page screenshots or status codes. Use Playwright/Sockpuppet Browser for new installations.

Advanced Volume Configuration

Proxy List Support

Mount a custom proxy configuration file:

volumes:
  - changedetection-data:/datastore
  - ./proxies.json:/datastore/proxies.json

See the proxy configuration wiki for format details.

SSL Certificate Mounting

volumes:
  - changedetection-data:/datastore
  - ./cert.pem:/app/cert.pem
  - ./privkey.pem:/app/privkey.pem
environment:
  - SSL_CERT_FILE=cert.pem
  - SSL_PRIVKEY_FILE=privkey.pem

Updating

Pull the latest images

docker compose pull

Restart services

docker compose up -d

Docker Compose will automatically recreate containers with updated images while preserving your data.

Network Configuration

Behind a Reverse Proxy

Comment out the ports section and use a custom network:

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    volumes:
      - changedetection-data:/datastore
    environment:
      - USE_X_SETTINGS=1
      - BASE_URL=https://changedetection.example.com
    networks:
      - proxy-network
    restart: unless-stopped

networks:
  proxy-network:
    external: true

volumes:
  changedetection-data:

Troubleshooting

Services won’t start

Check logs for all services:

docker compose logs

Or for a specific service:

docker compose logs changedetection

Browser automation not working

Verify the browser service is running:

docker compose ps

Check browser service logs:

docker compose logs browser-sockpuppet-chrome

Ensure the PLAYWRIGHT_DRIVER_URL or WEBDRIVER_URL environment variable is set correctly.

Permission issues

Reset volume permissions:

docker compose down
docker volume rm changedetection-data
docker compose up -d

Removing the volume will delete all data. Back up your datastore first.

Port conflicts on Mac

Change the port mapping to avoid Airplay conflicts:

ports:
  - 127.0.0.1:5050:5000

Out of memory errors with browser

Increase Docker memory limits or reduce concurrent Chrome processes:

browser-sockpuppet-chrome:
  environment:
    - MAX_CONCURRENT_CHROME_PROCESSES=5

Platform-Specific Notes

Raspberry Pi / ARM Devices

For ARM platforms, use the appropriate Selenium image:

browser-selenium-chrome:
  image: seleniarm/standalone-chromium:4.0.0-20211213

Playwright/Sockpuppet Browser also works on ARM64 devices.

Next Steps

Configuration

Configure notifications and advanced features

Browser Fetchers

Learn about different fetching methods

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

Quick Start

Basic Configuration

Environment Variables

Key Environment Variables

Reverse Proxy Configuration

Proxy Configuration

Plugin Installation

Browser Automation Setup

Option 1: Playwright with Sockpuppet Browser (Recommended)

Option 2: Selenium WebDriver (Legacy)

Advanced Volume Configuration

Proxy List Support

SSL Certificate Mounting

Updating

Network Configuration

Behind a Reverse Proxy

Troubleshooting

Services won’t start

Browser automation not working

Permission issues

Port conflicts on Mac

Out of memory errors with browser

Platform-Specific Notes

Raspberry Pi / ARM Devices

Next Steps

Configuration

Browser Fetchers

​Quick Start

​Basic Configuration

​Environment Variables

​Key Environment Variables

​Reverse Proxy Configuration

​Proxy Configuration

​Plugin Installation

​Browser Automation Setup

​Option 1: Playwright with Sockpuppet Browser (Recommended)

​Option 2: Selenium WebDriver (Legacy)

​Advanced Volume Configuration

​Proxy List Support

​SSL Certificate Mounting

​Updating

​Network Configuration

​Behind a Reverse Proxy

​Troubleshooting

​Services won’t start

​Browser automation not working

​Permission issues

​Port conflicts on Mac

​Out of memory errors with browser

​Platform-Specific Notes

​Raspberry Pi / ARM Devices

​Next Steps

Configuration

Browser Fetchers

Quick Start

Basic Configuration

Environment Variables

Key Environment Variables

Reverse Proxy Configuration

Proxy Configuration

Plugin Installation

Browser Automation Setup

Option 1: Playwright with Sockpuppet Browser (Recommended)

Option 2: Selenium WebDriver (Legacy)

Advanced Volume Configuration

Proxy List Support

SSL Certificate Mounting

Updating

Network Configuration

Behind a Reverse Proxy

Troubleshooting

Services won’t start

Browser automation not working

Permission issues

Port conflicts on Mac

Out of memory errors with browser

Platform-Specific Notes

Raspberry Pi / ARM Devices

Next Steps