Can I self-host Visualping?

301 lines · 13,900 bytes

You are Claude Code on the user's machine. The user has completed Prompt Zero: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny.

Run every command in this prompt on the server over `ssh vps` unless the step says otherwise.

Install changedetection.io 0.55.8 on that server, reachable at https://<DOMAIN>, behind the existing
Caddy with automatic TLS.

## 1. Preflight

If `<DOMAIN>` is still literal, ask the user for the hostname once and stop until they answer.
Its A record must already point at this server. Say two things when you ask. One: that hostname
becomes `BASE_URL` in the environment, and notification links and the reverse-proxy sense of
"where am I" use it, so a hostname that does not match the browser address produces wrong links.
Two: until the password step finishes, the UI would be open to anyone who can reach the
hostname; this install closes that door before the first public request by setting
`SALTED_PASS`, not a fictional `PASSWORD` env var.

changedetection.io needs 1024 MB of RAM available and 5 GB free on /srv. The 0.55.8 image
publishes amd64 and arm64. Python 3 on the host is required in step 3 to build the same password
hash upstream uses. Measure:

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
command -v python3 && python3 --version
```

If available RAM is under 1024 MB or free disk is under 5 GB, print both numbers and stop. Do not
install and hope. If `dig +short` prints nothing, print that and stop: Caddy cannot certify a
hostname that does not resolve. If `python3` is missing, install it from the distro packages
(`sudo apt-get install -y python3` on Debian/Ubuntu) or stop and say why.

This install does **not** include Playwright or sockpuppetbrowser. The plain HTTP fetcher works
for static HTML and many product pages. Sites that paint price or stock only after JavaScript
runs will look empty here until the user adds the browser sidecar later. Name that limit to the
user once in this step so it is not a surprise in week two.

## 2. Layout

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/changedetection /srv/changedetection/backups /srv/changedetection/data
ls -la /srv/changedetection
```

Assert: `ls -la` shows `backups` and `data` owned by the login user. `data` is the host side of
the `/datastore` mount: watches, snapshot history, and any Settings-stored password hash land
there. Nothing is written outside `/srv/changedetection`.

## 3. Secrets

One secret: the UI login password. Upstream does **not** read a `PASSWORD` environment variable.
It accepts either a password typed in Settings, or `SALTED_PASS`: base64 of a 32-byte salt plus a
pbkdf2-hmac-sha256 key at 100000 rounds, the same construction as `SaltyPasswordField` in the
0.55.8 source. Generate the plain password with openssl, hash it with python3, write both into
`.env`, and never print either value into the chat.

```bash
umask 077
LOGIN_PASSWORD="$(openssl rand -base64 24)"
export LOGIN_PASSWORD
SALTED_PASS="$(python3 - <<'PY'
import base64, hashlib, os, secrets
plain = os.environ.get("LOGIN_PASSWORD", "").encode("utf-8")
salt = secrets.token_bytes(32)
key = hashlib.pbkdf2_hmac("sha256", plain, salt, 100000)
print(base64.b64encode(salt + key).decode("ascii"))
PY
)"
cat > /srv/changedetection/.env <<EOF
BASE_URL=https://<DOMAIN>
LOGIN_PASSWORD=${LOGIN_PASSWORD}
SALTED_PASS=${SALTED_PASS}
EOF
chmod 600 /srv/changedetection/.env
umask 022
unset LOGIN_PASSWORD SALTED_PASS
ls -l /srv/changedetection/.env
```

Replace `<DOMAIN>` on the `BASE_URL` line with the real hostname before the block runs. Assert:
the file exists with mode `-rw-------`. Do not print `LOGIN_PASSWORD` or `SALTED_PASS`. Tell the
user their login password is only in that file, read once with
`grep LOGIN_PASSWORD /srv/changedetection/.env`, and put it in a password manager now.
`LOGIN_PASSWORD` is for humans; the process inside the container checks `SALTED_PASS` only.

## 4. compose.yml

```bash
cat > /srv/changedetection/compose.yml <<'EOF'
# changedetection.io · the deterministic fallback. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   docker ............. https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/README.md#docker
#   compose example .... https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/docker-compose.yml
#   password ........... https://github.com/dgtlmoon/changedetection.io/wiki/Password-protection
#   salted pass ........ SALTED_PASS in changedetectionio/flask_app.py at tag 0.55.8
#   playwright ......... https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher
#
# One service. Watches, history and the hashed UI password live under /datastore.
# SALTED_PASS and BASE_URL come from /srv/changedetection/.env (generated on the
# server). There is no PASSWORD env var in this software: the app checks a
# base64 salt+pbkdf2 hash under SALTED_PASS, or a password set in the Settings
# UI. This install sets SALTED_PASS so the UI is closed from first boot.
# No Playwright / sockpuppetbrowser sidecar: JavaScript-heavy pages need that
# second container and more RAM; the upgrade path is named in the prompts.
# Digest read from Docker Hub on 2026-08-07 for tag 0.55.8.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  changedetection:
    image: dgtlmoon/changedetection.io:0.55.8@sha256:5438423d5e906eff4e8f7886823482ad23f472bf7b8530ccaca89fb48c337882
    container_name: changedetection
    restart: unless-stopped
    env_file: /srv/changedetection/.env
    volumes:
      # Watches, snapshot history, and the Settings-stored password hash.
      - /srv/changedetection/data:/datastore
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8205.
      - "127.0.0.1:8205:5000"
EOF
cd /srv/changedetection && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one published port, no database container, no
browser sidecar. Do not add a Caddy service to this file: Caddy is already running under systemd
on this box.

## 5. Caddy and TLS

Write the site block under `/srv/changedetection/Caddyfile`, then append it to the live Caddyfile
with `<DOMAIN>` replaced by the real hostname. Copy the live file first: a syntax error here
takes down every other site on the box.

```bash
cat > /srv/changedetection/Caddyfile <<'EOF'
# changedetection.io · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://github.com/dgtlmoon/changedetection.io/wiki/Running-changedetection.io-behind-a-reverse-proxy
# and https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed, with
# <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under systemd
# on the host. There is no Caddy container anywhere in this project.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8205 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8205
}
EOF
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-changedetection
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
DOMAIN_HOST=<DOMAIN>
sed "s|<DOMAIN>|${DOMAIN_HOST}|g" /srv/changedetection/Caddyfile | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Set `DOMAIN_HOST` to the real hostname from step 1 before running `sed`. That is the house form:
no nested quotes around the replacement. Assert: `caddy validate` exits 0 and the reload exits
0. If validate fails, restore `/etc/caddy/Caddyfile.before-changedetection`, reload, and report
what it objected to. Caddy requests the certificate on the first request and renews it on its
own, so there is nothing to schedule.

## 6. Firewall

Two ports open, both Caddy's. These are idempotent, so on a box Prompt Zero configured they
change nothing:

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

80/tcp answers the ACME challenge and redirects to HTTPS, 443/tcp is the only way in, and 443/udp
is HTTP/3. 8205 stays closed because compose binds it to 127.0.0.1. Assert: `ufw status verbose`
prints `Status: active`, shows 80, 443/tcp and 443/udp, and no rule mentioning 8205 or 5000.

## 7. Start and verify

```bash
cd /srv/changedetection
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/); echo "$i $code"; case "$code" in 200|301|302|303|307|308) break ;; esac; sleep 5; done
curl -sS -o /dev/null -w 'unauth_status=%{http_code}\n' https://<DOMAIN>/
curl -sSL https://<DOMAIN>/ | grep -ci 'password'
docker compose ps
```

Assert all of the following, and print what you received for each. The loop ends with a 2xx or
3xx status. The unauthenticated status is `302` (or `401`/`403`): with `SALTED_PASS` set, the
app's `before_request` hook sends unauthenticated callers to the login view rather than the
dashboard. The `grep -ci password` count is greater than `0` after following redirects, because
the login form carries a password field. If the unauthenticated status is plain `200` with a
dashboard and no password field, stop: `SALTED_PASS` did not load (check `.env` mode, the
`env_file` line, and `docker compose config`). If Caddy returns 502 with a running container,
step 5 is the likely cause. A running container is not success.

STOP: tell the user to read `grep LOGIN_PASSWORD /srv/changedetection/.env` on the server,
open https://<DOMAIN>/ in a private window, sign in with that password, and confirm they see the
watches dashboard (empty is fine). Do not continue until they confirm.

After they confirm, re-check that a cold unauthenticated request is still refused:

```bash
curl -sS -o /dev/null -w 'still_unauth=%{http_code}\n' https://<DOMAIN>/
```

Assert: that status is still not a dashboard-serving bare `200` without auth. Print the code.

## 8. First backup and restore

One archive: the datastore (the real mounted state), the compose file, `.env`, and the live
Caddy site block. Take it now, before there is a month of watch history to lose.

```bash
cd /srv/changedetection
docker compose stop
sudo tar -czf /srv/changedetection/backups/changedetection-$(date +%F).tar.gz \
  -C /srv/changedetection data compose.yml .env \
  -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/changedetection/backups/
```

Assert: the archive exists and is non-empty. Print its size. Downtime is short; the container is
stopped on purpose so files under `data/` are not half-written. Never append `|| true` to this
tar: a failed backup must fail the step.

A backup on the same disk as the data is not a backup. Run this one from the user's machine, not
the server:

```bash
mkdir -p ~/backups/changedetection
scp vps:/srv/changedetection/backups/*.tar.gz ~/backups/changedetection/
```

To restore: `cd /srv/changedetection`, `docker compose down`, move aside the current `data` and
`.env`, untar the archive into `/srv/changedetection` (and put the Caddyfile back under
`/etc/caddy` if that is what was lost), then `docker compose up -d`. Tell the user which half
matters: `data/` is every watch and every snapshot, and `.env` is how they log in. Losing
`.env` without a copy of `LOGIN_PASSWORD` is a lockout (upstream also documents a
`removepassword.lock` escape hatch under `/datastore` if they ever need it). Losing `data/`
costs the product.

## 9. Updating later

New versions are listed at https://github.com/dgtlmoon/changedetection.io/releases. The image tag
tracks the release. Take a backup first, then edit the image line in
`/srv/changedetection/compose.yml` to the new tag and its digest:

```bash
cd /srv/changedetection
docker compose pull
docker compose up -d
docker compose logs --tail 30 changedetection
```

Re-run step 7's unauthenticated-refusal check after every upgrade. If the user later needs
JavaScript rendering, the upgrade path is the upstream sockpuppetbrowser / Playwright sidecar:
add a browser service, set `PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000` (or the
name they chose), raise RAM, and follow
https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher. Do not add that
sidecar in this install unless they explicitly ask after reading the memory cost.

## 10. What will probably go wrong

You will add a watch against a modern storefront, wait for the interval, and get a snapshot that
looks like an empty shell or a "enable JavaScript" page. I hit that on the first price I cared
about. This install ships the plain fetcher only; it does not run a browser. The fix is not
"check more often". It is either a CSS/JSON selector against HTML that really is in the first
response, or the Playwright/sockpuppetbrowser path named in step 9. Until one of those is true,
a polite interval just records the same empty shell more carefully.

## 11. Out of scope

- Do not add a Caddy container to the compose file. Caddy is already running under systemd on
  this box, and a second one would fight it for 80 and 443.
- Do not publish 8205 on `0.0.0.0` or open it in the firewall. Caddy is the only way in.
- Do not invent a `PASSWORD` environment variable. Upstream does not read one.
- Do not add Playwright, sockpuppetbrowser, Selenium, or a second browser container unless the
  user explicitly asks after the limitation in steps 1 and 9 is clear.
- Do not skip the first backup or the unauthenticated-refusal assert.

This path is slower: you paste every command yourself, and there is nobody watching the output
but you. If you can run Claude Code, use the other tab.

You are installing changedetection.io 0.55.8 on a VPS where Prompt Zero is done: `ssh vps`
works, Docker and Caddy are installed, the firewall is default-deny. Run everything over
`ssh vps` unless a step says otherwise, and replace `<DOMAIN>` with the hostname whose A record
already points at the box.

Read these before step 1. The hostname becomes `BASE_URL`, so it must match what you type in the
browser. Upstream has no `PASSWORD` env var: this install builds `SALTED_PASS` (salt +
pbkdf2-hmac-sha256, base64) the same way the Settings UI does, so the UI is closed from first
boot. There is no Playwright or sockpuppetbrowser container here; JavaScript-only storefronts may
snapshot as empty shells until you add that sidecar later (wiki: Playwright-content-fetcher).


Also know: the datastore path inside the container is `/datastore`, which this install binds to
`/srv/changedetection/data` on the host. Backups must archive that directory, not an empty sibling
folder. Notifications use Apprise URL schemes you paste into a watch; nothing here signs you up
for Discord, Slack or email for you. Polite recheck intervals matter: this is a watcher, not a
load generator.

If you forget the UI password later, upstream documents an escape hatch: create
`/datastore/removepassword.lock` inside the container (or `data/removepassword.lock` on the host)
and restart, then set a new password. Prefer restoring `.env` from backup instead.

## 1. Preflight

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
command -v python3 && python3 --version
```

You should see: at least `1024` MB available, at least `5` G free, `amd64` or `arm64`, your
server's IP on the dig line, and a python3 version. If dig is empty, add the A record and wait.
If python3 is missing, install it (`sudo apt-get install -y python3` on Debian/Ubuntu) before step 3.

If free memory is under 1024 MB, stop. Adding the browser sidecar later will want more still; do
not start from a box that is already below the floor. arm/v7 is not the target of this pin's
verified path; stick to amd64 or arm64.



## 2. Layout

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/changedetection /srv/changedetection/backups /srv/changedetection/data
ls -la /srv/changedetection
```

You should see: `backups` and `data` under `/srv/changedetection`, owned by your login user.
`data` is the host side of `/datastore` (watches, history, settings).

## 3. Secrets

One secret. Generate on the server. Do not paste the password into this chat after it prints in
your terminal for the `grep` read later.

```bash
umask 077
LOGIN_PASSWORD="$(openssl rand -base64 24)"
export LOGIN_PASSWORD
SALTED_PASS="$(python3 - <<'PY'
import base64, hashlib, os, secrets
plain = os.environ.get("LOGIN_PASSWORD", "").encode("utf-8")
salt = secrets.token_bytes(32)
key = hashlib.pbkdf2_hmac("sha256", plain, salt, 100000)
print(base64.b64encode(salt + key).decode("ascii"))
PY
)"
cat > /srv/changedetection/.env <<EOF
BASE_URL=https://<DOMAIN>
LOGIN_PASSWORD=${LOGIN_PASSWORD}
SALTED_PASS=${SALTED_PASS}
EOF
chmod 600 /srv/changedetection/.env
umask 022
unset LOGIN_PASSWORD SALTED_PASS
ls -l /srv/changedetection/.env
```

Replace `<DOMAIN>` on `BASE_URL` with your real hostname before you run the block. You should
see mode `-rw-------`. Read the password later with
`grep LOGIN_PASSWORD /srv/changedetection/.env` and put it in a password manager.
`LOGIN_PASSWORD` is for you; the container checks `SALTED_PASS` only.

If `python3` is missing on a minimal image, install it before this block. Do not try to invent a
a fictional PASSWORD environment line; the process ignores it. Do not commit the env file under /srv to a git repo.



## 4. compose.yml

Paste this whole block. It must match the project's compose file byte for byte between the
markers.

```bash
cat > /srv/changedetection/compose.yml <<'EOF'
# changedetection.io · the deterministic fallback. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   docker ............. https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/README.md#docker
#   compose example .... https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/docker-compose.yml
#   password ........... https://github.com/dgtlmoon/changedetection.io/wiki/Password-protection
#   salted pass ........ SALTED_PASS in changedetectionio/flask_app.py at tag 0.55.8
#   playwright ......... https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher
#
# One service. Watches, history and the hashed UI password live under /datastore.
# SALTED_PASS and BASE_URL come from /srv/changedetection/.env (generated on the
# server). There is no PASSWORD env var in this software: the app checks a
# base64 salt+pbkdf2 hash under SALTED_PASS, or a password set in the Settings
# UI. This install sets SALTED_PASS so the UI is closed from first boot.
# No Playwright / sockpuppetbrowser sidecar: JavaScript-heavy pages need that
# second container and more RAM; the upgrade path is named in the prompts.
# Digest read from Docker Hub on 2026-08-07 for tag 0.55.8.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  changedetection:
    image: dgtlmoon/changedetection.io:0.55.8@sha256:5438423d5e906eff4e8f7886823482ad23f472bf7b8530ccaca89fb48c337882
    container_name: changedetection
    restart: unless-stopped
    env_file: /srv/changedetection/.env
    volumes:
      # Watches, snapshot history, and the Settings-stored password hash.
      - /srv/changedetection/data:/datastore
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8205.
      - "127.0.0.1:8205:5000"
EOF
cd /srv/changedetection && docker compose config >/dev/null && echo "compose OK"
```

You should see: `compose OK`. One service, port 8205 on loopback only. Do not add a Caddy
service here; Caddy already runs under systemd on the host.

## 5. Caddy and TLS

Write the site block, then append it with the hostname substituted. Copy the live Caddyfile
first.

```bash
cat > /srv/changedetection/Caddyfile <<'EOF'
# changedetection.io · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://github.com/dgtlmoon/changedetection.io/wiki/Running-changedetection.io-behind-a-reverse-proxy
# and https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed, with
# <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under systemd
# on the host. There is no Caddy container anywhere in this project.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8205 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8205
}
EOF
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-changedetection
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
DOMAIN_HOST=<DOMAIN>
sed "s|<DOMAIN>|${DOMAIN_HOST}|g" /srv/changedetection/Caddyfile | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Set `DOMAIN_HOST` to your real hostname (no quotes inside the sed replacement). `caddy validate`
and the reload must both exit 0. If validate fails, restore
`/etc/caddy/Caddyfile.before-changedetection`, reload, and fix the syntax. Caddy requests the
certificate on the first request and renews it on its own.

## 6. Firewall

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

You should see: `Status: active`, rules for 80 and 443, and nothing for 8205 or 5000. 8205 stays
closed because compose binds it to 127.0.0.1.

## 7. Start and verify

```bash
cd /srv/changedetection
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/); echo "$i $code"; case "$code" in 200|301|302|303|307|308) break ;; esac; sleep 5; done
curl -sS -o /dev/null -w 'unauth_status=%{http_code}\n' https://<DOMAIN>/
curl -sSL https://<DOMAIN>/ | grep -ci 'password'
docker compose ps
```

You should see: a 2xx or 3xx from the loop; `unauth_status` of `302` (or `401`/`403`), not an
open dashboard; a password-field count greater than `0` after following redirects. If unauth is a
bare `200` with the watches UI and no password field, `SALTED_PASS` did not load: check `.env`
mode 600, the `env_file` line, and `docker compose config`. If Caddy returns 502, re-check step
5. A running container alone is not success.

Common misreads on this step: a `200` on the loop can still be the login page after a redirect
chain your curl did not show. Always print `unauth_status` without `-L` and the password-field
count with `-L`. Empty `docker compose ps` means pull or start failed; read
`docker compose logs --tail 40 changedetection` before changing Caddy. If validate passed and
the container is healthy but the public URL times out, the A record or firewall step is wrong,
not the image pin.



STOP: read `grep LOGIN_PASSWORD /srv/changedetection/.env` on the server, open
https://<DOMAIN>/ in a private window, sign in, and confirm you see the watches dashboard (empty
is fine). Do not continue until they confirm.

Then re-check:

```bash
curl -sS -o /dev/null -w 'still_unauth=%{http_code}\n' https://<DOMAIN>/
```

That status must still show an unauthenticated refusal, not an open dashboard.

## 8. First backup and restore

Archive the real mounted state (`data/` is `/datastore`), compose, `.env`, and the live Caddyfile.

```bash
cd /srv/changedetection
docker compose stop
sudo tar -czf /srv/changedetection/backups/changedetection-$(date +%F).tar.gz \
  -C /srv/changedetection data compose.yml .env \
  -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/changedetection/backups/
```

The archive must exist and be non-empty; print its size. Do not append `|| true` to tar. From
your laptop (not the server):

```bash
mkdir -p ~/backups/changedetection
scp vps:/srv/changedetection/backups/*.tar.gz ~/backups/changedetection/
```

To restore: `cd /srv/changedetection`, `docker compose down`, move aside `data` and `.env`, untar
into `/srv/changedetection` (restore `/etc/caddy/Caddyfile` if that half was lost), then
`docker compose up -d`. `data/` is the watches; `.env` is the login. Upstream also documents
`removepassword.lock` under `/datastore` if you ever need an emergency password reset.

After restore, re-run the unauthenticated-refusal curl from step 7 before you trust the UI. If
`.env` restored but `data/` did not, you can log in to an empty instance. If `data/` restored but
`.env` did not, you still have the watches on disk and need either the old `LOGIN_PASSWORD` or the
`removepassword.lock` procedure, then a new password in Settings.



## 9. Updating later

Releases: https://github.com/dgtlmoon/changedetection.io/releases. Backup first, edit the image
line in `/srv/changedetection/compose.yml` to the new tag and digest, then:

```bash
cd /srv/changedetection
docker compose pull
docker compose up -d
docker compose logs --tail 30 changedetection
```

Re-run the unauthenticated-refusal check from step 7 after every upgrade. For JavaScript-heavy
pages later, add the sockpuppetbrowser / Playwright sidecar and
`PLAYWRIGHT_DRIVER_URL` per
https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher, and budget the
extra RAM. Do not add it until you know you need it.

When you pin a new digest, record it in a note next to the release tag so the next upgrade is a
diff you can read. If an upgrade restarts into a crash loop, roll back the image line to the
previous pin, `docker compose up -d`, and only then inspect migration logs. Do not run two
changedetection containers against the same `data/` directory.



## 10. What will probably go wrong

You will add a watch against a modern storefront, wait for the interval, and get a snapshot that
looks like an empty shell or a "enable JavaScript" page. This install ships the plain fetcher
only; it does not run a browser. Checking more often will not fill an empty shell. Fix it with a
selector against HTML that really is in the first response, or with the Playwright path in step
9. The second common failure is a notification URL you never tested: wire Apprise, send a
deliberate change, and confirm the channel before trusting silence.

A third failure mode is `BASE_URL` disagreeing with the browser hostname: notification links and
some UI redirects point at whatever was written into `.env`. If you rename the site later, update
`BASE_URL` and recreate the container so the new value loads. Fourth: filling the disk under
`data/` with long snapshot history. Prune old history from the UI when the volume grows past what
you meant to keep, and keep the off-box backup current before you prune.



## 11. Out of scope

- Do not add a Caddy container to compose. Caddy already runs under systemd on this host.
- Do not publish 8205 on `0.0.0.0` or open it in the firewall.
- Do not invent a `PASSWORD` environment variable. Upstream does not read one.
- Do not add Playwright, sockpuppetbrowser, or Selenium unless you explicitly decide to after
  reading the memory cost in step 9.
- Do not skip the first backup or the unauthenticated-refusal assert.


Hostname discipline: every place you type the public name must match. That is `BASE_URL` in
`.env`, the Caddy site address after sed, and the URL you open in the browser. A missing A
record fails Caddy; a wrong `BASE_URL` fails links and notification targets.

Security discipline: until `SALTED_PASS` is present and loaded, the UI is open. This path writes
the hash before `docker compose up`. If you ever recreate `.env` without `SALTED_PASS`, the next
start is open again. After every recreate, re-run the unauthenticated curl and confirm a
redirect or refusal, not a bare dashboard.

State discipline: `/srv/changedetection/data` is the product. Watches, history, tags and any
password later saved through Settings live there. Backups that archive only `compose.yml` are
not backups of changedetection.

Fetcher discipline: the plain HTTP client is what runs today. Visual Selector, browser steps and
many restock flows expect Playwright. Plan RAM before you uncomment a browser service. The
upstream wiki page for that is Playwright-content-fetcher; follow it when you need it, not
before.

Operational discipline: first backup tonight, off the box. Second backup after you add the first
ten watches. Update by pin and digest, never by floating `latest`. This path is NOT YET VERIFIED
on a clean harness machine; treat the asserts as the contract and stop when they fail.

If a step's assert fails, name the earlier step that most likely caused it before changing
anything else. Preflight failures are step 1. Missing password on the public URL is step 3.
Compose config errors are step 4. Certificate or 502 problems are step 5. Open ports that should
be closed are step 6. Dashboard without a login form is step 3 or 7. Empty backups are step 8.

NOT YET VERIFIED: no harness run has been recorded against this install path.

282 lines · 12,859 bytes

You are Claude Code on the user's own computer. There is no server and no Prompt Zero:
everything in this prompt runs on this machine and stays on it.

Run every command on this computer, in the shell you are already in. Nothing in this prompt
uses ssh.

Install changedetection.io 0.55.8 under ~/selfhost/changedetection, answering at
http://localhost:8205.

## 1. Preflight

Say this to the user before step 2 runs, because it decides whether they want this install at
all. Checks only run while this computer is awake. A price drop at 3am is invisible until the
laptop opens again. What they get is a private watcher over pages they care about that works
while they are at this desk. Also: this install uses the plain HTTP fetcher only, with no
Playwright or sockpuppetbrowser sidecar, so JavaScript-only storefronts may snapshot as empty
shells until they add that path later.

Detect the OS and measure the machine:

```bash
uname -s
case "$(uname -s)" in
  Darwin) vm_stat | awk '/page size/{p=$8} /free|inactive/{s+=$3} END {printf "%d MB available\n", s*p/1048576}' ;;
  Linux) . /etc/os-release && echo "$ID $VERSION_CODENAME"; free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}' ;;
  MINGW*|MSYS*) powershell -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory" | awk '$1+0 {printf "%d MB available\n", $1/1024}' ;;
esac
df -h ~
command -v python3 && python3 --version
```

`Darwin` is macOS, `Linux` is Linux, `MINGW` or `MSYS` is Windows under Git Bash. On Linux the
distribution ID and codename print next, for step 2. changedetection.io needs 1024 MB of RAM
available and 5 GB free on the home disk, and the image publishes amd64 and arm64. Every branch
prints free memory, so one floor covers all three; on macOS and Windows it is the host's, and
Docker Desktop takes its allocation out of it. If available RAM is under 1024 MB or free disk is
under 5 GB, print both numbers and stop. Do not install and hope. Python 3 is required in step 4
to build `SALTED_PASS` the way upstream does; if it is missing, install it (Xcode CLT / brew /
the distro package / the python.org installer) or stop and say why.

## 2. Docker

Check before installing anything:

```bash
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker MISSING"
docker compose version 2>/dev/null || true
```

If that printed `docker OK` and a compose version, skip to step 3.

Otherwise, install Docker for the OS step 1 detected:

- macOS: if `command -v brew` succeeds, run `brew install --cask docker`. If there is no
  Homebrew, STOP: tell the user to download Docker Desktop from
  https://www.docker.com/products/docker-desktop/ and install it, and wait until they
  confirm. Either way, then STOP: tell the user to open Docker Desktop once, accept its
  terms, and wait for the whale icon to say it is running. Do not continue until they confirm.
- Windows: run `winget install -e --id Docker.DockerDesktop`. If winget is missing or the
  install fails, STOP: tell the user to download Docker Desktop from the URL above and
  install it, and wait until they confirm. Docker Desktop configures WSL 2 itself and may
  ask for a reboot; if it does, STOP and tell the user to reboot and come back, this
  prompt resumes at this step. Then STOP: have the user open Docker Desktop, accept its
  terms, and confirm it says running.
- Linux, Debian or Ubuntu: install Docker Engine from download.docker.com's apt
  repository, with its signing key saved to a file first, never piped into a shell. The
  fence is guarded, a no-op on anything but a Linux with apt:

```bash
if [ "$(uname -s)" = "Linux" ] && command -v apt-get >/dev/null 2>&1; then
  sudo apt-get update
  sudo apt-get install -y ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo "$ID") $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
  sudo apt-get update
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
  sudo usermod -aG docker "$USER"
fi
```

  Adding the user to the docker group is root-equivalent on this machine; say that to the
  user in one sentence, and tell them the group change lands at their next login.
- Linux, anything else: STOP. Tell the user to install Docker Engine and the compose
  plugin with their distribution's package manager, and to run this prompt again once
  `docker info` works.

Assert: `docker info` exits 0 and `docker compose version` prints a version. Do not
continue without both.

## 3. Layout

```bash
mkdir -p ~/selfhost/changedetection/data ~/selfhost/changedetection/backups
ls -la ~/selfhost/changedetection
```

Assert: `data` and `backups` exist under `~/selfhost/changedetection`. `data` is the host side of
the `/datastore` mount.

## 4. Secrets

One secret: the UI login password. Upstream does not read a `PASSWORD` environment variable. It
checks `SALTED_PASS` (base64 of salt plus pbkdf2-hmac-sha256), matching `SaltyPasswordField` at
tag 0.55.8. Generate on this machine and never print the values into the chat.

```bash
umask 077
LOGIN_PASSWORD="$(openssl rand -base64 24)"
export LOGIN_PASSWORD
SALTED_PASS="$(python3 - <<'PY'
import base64, hashlib, os, secrets
plain = os.environ.get("LOGIN_PASSWORD", "").encode("utf-8")
salt = secrets.token_bytes(32)
key = hashlib.pbkdf2_hmac("sha256", plain, salt, 100000)
print(base64.b64encode(salt + key).decode("ascii"))
PY
)"
cat > ~/selfhost/changedetection/.env <<EOF
BASE_URL=http://localhost:8205
LOGIN_PASSWORD=${LOGIN_PASSWORD}
SALTED_PASS=${SALTED_PASS}
EOF
chmod 600 ~/selfhost/changedetection/.env
umask 022
unset LOGIN_PASSWORD SALTED_PASS
ls -l ~/selfhost/changedetection/.env
```

Assert: the file exists with mode `-rw-------` (on Windows mode bits are advisory). Do not print
the password. Tell the user to read it with `grep LOGIN_PASSWORD ~/selfhost/changedetection/.env`
when they sign in.

## 5. compose.yml

```bash
cat > ~/selfhost/changedetection/compose.yml <<'EOF'
# changedetection.io · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   docker ............. https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/README.md#docker
#   compose example .... https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/docker-compose.yml
#   password ........... https://github.com/dgtlmoon/changedetection.io/wiki/Password-protection
#
# One service on the computer you are sitting at. Paths are relative to
# ~/selfhost/changedetection/. SALTED_PASS and BASE_URL come from ./.env.
# No Playwright sidecar on this path either. Digest read from Docker Hub on
# 2026-08-07 for tag 0.55.8.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  changedetection:
    image: dgtlmoon/changedetection.io:0.55.8@sha256:5438423d5e906eff4e8f7886823482ad23f472bf7b8530ccaca89fb48c337882
    container_name: changedetection
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./data:/datastore
    ports:
      # Loopback only: no other device on the wifi can reach 8205.
      - "127.0.0.1:8205:5000"
EOF
cd ~/selfhost/changedetection && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one published port, one bind mount for state.

## 6. Nothing is public

No reverse proxy, no certificate, no firewall rule, and each is a decision. There is no hostname
to resolve. A certificate attests a public name and nothing here has one; browsers treat
http://localhost as a secure context anyway. Nothing is published beyond loopback, so no port
needs closing.

8205 is bound to 127.0.0.1, this computer only. The user's phone cannot reach it, nor a laptop on
the same wifi, nor anyone on the internet. Confirm the binding:

```bash
grep -c '"127.0.0.1:' ~/selfhost/changedetection/compose.yml
```

Assert: that count is exactly `1`. The fetcher still reaches the internet normally: a loopback
binding governs what can arrive, not what the container can call.

## 7. Start and verify

```bash
cd ~/selfhost/changedetection
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' http://localhost:8205/); echo "$i $code"; case "$code" in 200|301|302|303|307|308) break ;; esac; sleep 5; done
curl -sS -o /dev/null -w 'unauth_status=%{http_code}\n' http://localhost:8205/
curl -sSL http://localhost:8205/ | grep -ci 'password'
docker compose ps
```

Assert all of the following, and print what you received for each. The unauthenticated status is
`302` (or `401`/`403`): with `SALTED_PASS` set, unauthenticated callers hit the login view, not
the dashboard. The password-field count after following redirects is greater than `0`. If the
status is a bare dashboard `200` with no password field, stop and check `.env` and
`docker compose config`. If `port is already allocated` came back, find what holds 8205
(`lsof -nP -iTCP:8205 -sTCP:LISTEN`, `ss -ltnp | grep 8205` on Linux,
`netstat -ano | findstr :8205` on Windows) and stop until the user frees it. A running container
is not success.

STOP: tell the user to read `grep LOGIN_PASSWORD ~/selfhost/changedetection/.env`, open
http://localhost:8205/, sign in, and confirm they see the watches dashboard (empty is fine). Do not continue until they confirm.

Then re-check refusal:

```bash
curl -sS -o /dev/null -w 'still_unauth=%{http_code}\n' http://localhost:8205/
```

Assert: still not an open dashboard.

## 8. First backup and restore

One archive: the datastore, the compose file, and `.env`. No Caddyfile on this path.

```bash
cd ~/selfhost/changedetection
docker compose stop
tar -C ~/selfhost/changedetection -czf ~/selfhost/changedetection/backups/changedetection-$(date +%F).tar.gz data compose.yml .env
docker compose start
ls -lh ~/selfhost/changedetection/backups/
```

Assert: the archive exists and is non-empty. Print its size. The container is stopped on purpose
so files under `data/` are not half-written. Never append `|| true` to this tar.

That archive sits on the same disk as the data, which is not a backup, and on a laptop the disk
and the machine fail together. Ask the user for a destination that leaves this computer, a folder
their sync service watches or a USB stick, and copy it there with `cp`. In Git Bash a Windows
drive is written `/d/Backups`, not `D:\Backups`; confirm it exists before copying. Assert: the
user confirms the filename is listed there. If they have nowhere, say plainly that this install
has no backup.

To restore: `cd ~/selfhost/changedetection`, `docker compose down`, move aside `data` and `.env`,
untar the archive there, then `docker compose up -d`. `data/` is every watch; `.env` is how they
log in.

## 9. Updating later

New versions are listed at https://github.com/dgtlmoon/changedetection.io/releases. Take a backup
first, then edit the image line in ~/selfhost/changedetection/compose.yml to the new tag and
digest:

```bash
cd ~/selfhost/changedetection
docker compose pull
docker compose up -d
docker compose logs --tail 30 changedetection
```

Re-run step 7's unauthenticated-refusal check after every upgrade. JavaScript-heavy pages need
the Playwright/sockpuppetbrowser sidecar documented at
https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher; this local install
does not add it unless the user explicitly asks after reading the memory cost.

## 10. What will probably go wrong

I closed the lid on a Friday, opened the dashboard on Monday, and three watches had last run
Thursday night. The machine was asleep, so no check ran, and a check that never ran leaves no
diff behind. That is the honest shape of a watcher on a laptop. Turn on Docker Desktop's
start-at-login setting, and after any reboot run
`cd ~/selfhost/changedetection && docker compose up -d` before believing a "no change" figure.
The second failure mode is the empty JavaScript snapshot named in step 1: more frequent checks
will not fill it.

## 11. Out of scope

- Do not expose this to the internet.
- Do not configure port forwarding on the router.
- Do not add a reverse proxy or TLS.
- Do not rebind 8205 to 0.0.0.0 so a phone on the wifi can load the UI. That puts an
  authenticated app on every network this machine joins, and the password is only as strong as
  the one in `.env`.
- Do not invent a `PASSWORD` environment variable.
- Do not add Playwright or sockpuppetbrowser unless the user explicitly asks after the
  limitation is clear.

# changedetection.io · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   docker ............. https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/README.md#docker
#   compose example .... https://github.com/dgtlmoon/changedetection.io/blob/0.55.8/docker-compose.yml
#   password ........... https://github.com/dgtlmoon/changedetection.io/wiki/Password-protection
#
# One service on the computer you are sitting at. Paths are relative to
# ~/selfhost/changedetection/. SALTED_PASS and BASE_URL come from ./.env.
# No Playwright sidecar on this path either. Digest read from Docker Hub on
# 2026-08-07 for tag 0.55.8.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  changedetection:
    image: dgtlmoon/changedetection.io:0.55.8@sha256:5438423d5e906eff4e8f7886823482ad23f472bf7b8530ccaca89fb48c337882
    container_name: changedetection
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./data:/datastore
    ports:
      # Loopback only: no other device on the wifi can reach 8205.
      - "127.0.0.1:8205:5000"