This Docker Compose stack provides a changedetection.io instance with Playwright browser steps support and ready to use configuration for using Tor for all your watches, including special optimizations for .onion sites.
-
Clone this repository
-
Copy the
.env.examplefile to.envand customize values:cp .env.example .env nano .env # Edit settings as needed -
Start the stack:
docker compose up -d
-
Access the services:
- Main UI: https://localhost
- ChangeDetection UI: https://monitor.localhost
For more details on accessing services, see ACCESS.md.
This stack uses a secure, isolated network architecture with the following design principles:
- Nginx is the only publicly accessible service
- Postgres database is isolated and can only communicate with the main app
- Playwright browser can only connect to changedetection and torprivoxy
- Torprivoxy has access to the outside world to connect to Tor network
- All internal services use isolated Docker networks for secure communication
For more details, see the NETWORK.md documentation and view the network diagram.
This stack includes individual resource limits for each service to ensure optimal performance and prevent resource exhaustion. The default limits are configured as follows:
| Service | Memory Limit | CPU Limit | Purpose |
|---|---|---|---|
| ChangeDetection | 512M | 0.5 | Main monitoring service - adequate for watch processing |
| PostgreSQL | 256M | 0.2 | Database - typically uses minimal resources |
| Tor/Privoxy | 256M | 0.2 | Proxy service - minimal for proxy operations |
| Browser (Playwright) | 768M | 0.8 | Browser automation - needs substantial memory |
| Nginx | 128M | 0.1 | Reverse proxy - very lightweight |
| Next.js App | 256M | 0.3 | Web interface - reasonable for Node.js app |
You can adjust these limits in your .env file based on your system specifications and usage patterns:
# Example: Increase changedetection memory for heavy workloads
MEMORY_LIMIT_CHANGEDETECTION=1G
CPU_LIMIT_CHANGEDETECTION=1.0
# Example: Reduce browser resources for lighter usage
MEMORY_LIMIT_BROWSER=512M
CPU_LIMIT_BROWSER=0.5Guidelines for adjustment:
- ChangeDetection: Increase if monitoring many sites or using complex selectors
- Browser: Increase if experiencing timeouts or memory issues with JavaScript-heavy sites
- PostgreSQL: Usually doesn't need adjustment unless storing large amounts of historical data
- Tor/Privoxy: Rarely needs adjustment - these are lightweight services
- Nginx: Very lightweight - rarely needs more resources
- Next.js: Increase if the web interface feels slow or unresponsive
After modifying resource limits, restart the stack:
docker compose down
docker compose up -dYou can monitor resource usage with:
docker statsThis setup has been specially optimized for accessing Tor .onion sites:
When adding .onion sites to ChangeDetection.io:
- Use the Browser/JavaScript fetch method
- Set longer timeouts (120+ seconds)
- Reduce check frequency (once per 6-12 hours)
- Always enable "Ignore SSL Errors"
- Try manually visiting the site first with the
visit-onion-site.shscript - For persistent issues, check the TOR-TROUBLESHOOTING.md guide
This stack is using avpnusr/torprivoxy as HTTP proxy to tunnel your requests through the Tor network. Make sure you have selected "Tor Network" within the "Request" tab of the given watch. By default it's enabled for all watches.
You can disable using tor for single watches by choosing "Direct" within the "Request" tab of the given watch.
Make sure the proxies.json is present in the toplevel of your datastore directory if you run into problems. The content of proxies.json is based on the changedetection.io documentation.
This stack has been hardened with several security best practices:
- Services bind to localhost by default (configurable in
.env) - Non-root users are used where possible for all services
- Container privileges are restricted
- Database uses secure authentication methods
- Volumes use explicit permissions
- Sensitive information is stored in environment variables
- See SECURITY.md for more details on implementation
If you encounter permission-related issues when running with non-root users:
- See PERMISSION-TROUBLESHOOTING.md for solutions to common problems
- Each service is configured to use appropriate user permissions by default
All services use Docker's JSON logging driver with:
- Log rotation (max 3 files of 10MB each)
- Log compression to save disk space
- Configurable via standard Docker logging options
See SMTP-SETUP.md for detailed instructions on setting up email notifications.
If you encounter issues with Tor connectivity or .onion sites:
- Check the TOR-TROUBLESHOOTING.md guide
- Use the utility scripts above to diagnose problems
- Examine container logs with
docker-compose logs <service-name>
- Avoid monitoring .onion sites too frequently (they're often slower and less reliable)
- Try different fetch methods if one doesn't work
- Some .onion sites may implement CAPTCHAs or other anti-bot measures
- If a site suddenly goes offline, try at different times of day (onion sites can be inconsistent)
- Use CSS selectors to focus on just the important content
To configure email notifications:
-
Run the setup script:
./setup-smtp.sh
-
Follow the prompts to configure your SMTP settings with your email provider.
-
After configuration, restart the application to apply changes:
docker compose restart main-app
For detailed instructions and troubleshooting tips, see SMTP-SETUP.md.
An example watch is provided within url-watches.json. It will check the Tor api and returns your exit IP and if the connection was established via the Tor nework.
I do not own any of the projects. Credits go to the maintainers of each project.