Can I self-host UptimeRobot?

254 lines · 11,075 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 Uptime Kuma 2.5.0 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. Uptime Kuma needs 512 MB of RAM available and
5 GB free on /srv, and the 2.5.0 image covers amd64 and arm64.

```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>
```

If RAM is under 512 MB or disk under 5 GB, print both numbers and stop. If `dig +short` prints
nothing, print that and stop: Caddy cannot certify a hostname that does not resolve.

One thing to say out loud to the user before installing a monitor on the machine it will be
monitoring: this box cannot tell them it is down. If they have another server, this belongs on
the other one.

## 2. Layout

The image runs as the `node` user, uid 1000, so the data directory belongs to 1000 and not to
the login user. `db-config.json` is written now, before the first boot, because it is what
picks the database: with that file present Uptime Kuma uses SQLite and skips its database
setup screen entirely.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/uptime-kuma /srv/uptime-kuma/backups
sudo install -d -m 750 -o 1000 -g 1000 /srv/uptime-kuma/data
printf '{\n    "type": "sqlite"\n}\n' | sudo tee /srv/uptime-kuma/data/db-config.json >/dev/null
sudo chown 1000:1000 /srv/uptime-kuma/data/db-config.json
ls -la /srv/uptime-kuma/data
```

Assert: `ls -la` shows `db-config.json` owned by `1000`. Nothing is written outside
/srv/uptime-kuma, and the data directory is on local disk, because SQLite on a network mount
corrupts quietly and weeks later.

## 3. Secrets

No secret is generated for this install, and there is no `.env` file. Uptime Kuma's only
credential is the administrator account, and it is created in a browser at step 7 rather than
written into a file here. That is why this block has nothing to run.

Say one thing to the user now: between the container starting and them creating that account,
the setup screen is open to whoever reaches the hostname first. Step 7 is written to make that
window as short as it can be, and it is a hard stop for exactly that reason.

## 4. compose.yml

```bash
cat > /srv/uptime-kuma/compose.yml <<'EOF'
# Uptime Kuma · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   compose shape ...... https://github.com/louislam/uptime-kuma/blob/master/compose.yaml
#   install notes ...... https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install
#   reverse proxy ...... https://github.com/louislam/uptime-kuma/wiki/Reverse-Proxy
#
# One container. There is no Caddy service here: Prompt Zero already runs Caddy
# under systemd on the host, and a second one in a container would fight it for
# 80 and 443. Upstream pins the floating `2` tag and publishes 3001 on every
# interface; this file pins the exact release and binds to loopback instead. The
# image runs as the node user (uid 1000), hence the ownership in step 2. Tag and
# digest are the 2.5.0 release read from Docker Hub on 2026-08-05, for
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.0@sha256:a8610b3b4c38077922ba51b036691e06887d7cefd91fe620fd3d6d23d03dc240
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      # kuma.db and db-config.json both live here. Local disk only: SQLite
      # needs real POSIX file locks, and a network mount corrupts it quietly.
      - /srv/uptime-kuma/data:/app/data
    ports:
      # Loopback only. The Caddy that Prompt Zero installed on the host is the
      # only thing that can reach this port, and 8091 never enters the firewall.
      - "127.0.0.1:8091:3001"
EOF
cd /srv/uptime-kuma && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. The container serves on 3001 inside itself and 8091 is bound
to 127.0.0.1 on the host, so the only route in is Caddy. Do not add a Caddy service to this
file: Caddy is already running under systemd on this box, and a container claiming 80 and 443
would fail to start and take every other site down with it.

## 5. Caddy and TLS

Append the block below with `<DOMAIN>` replaced by the real hostname. Copy the file first: a
syntax error takes down every site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-uptime-kuma
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Uptime Kuma · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://github.com/louislam/uptime-kuma/wiki/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
	}

	# The dashboard is a WebSocket application. Caddy negotiates the upgrade on
	# its own, so there are no Upgrade or Connection headers to set by hand,
	# which is the step every nginx guide spends a paragraph on.
	#
	# 8091 is the loopback port compose publishes; it is never in the firewall.
	reverse_proxy 127.0.0.1:8091
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Assert: both exit 0. If validate fails, restore /etc/caddy/Caddyfile.before-uptime-kuma,
reload, and report what it objected to. Caddy gets the certificate on the first request and
renews it with no cron job.

## 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, 443/udp
is HTTP/3. 8091 stays closed: bound to 127.0.0.1, a rule for it would cover traffic that cannot
arrive, and if it appears there a previous run left it, which `sudo ufw delete allow 8091`
fixes. Assert: `ufw status verbose` prints `Status: active`, shows 80, 443/tcp and 443/udp, and
no rule for 8091.

## 7. Start and verify

The image's own health check allows a three-minute start period, so give the first boot time
before treating anything as broken.

```bash
cd /srv/uptime-kuma
docker compose pull
docker compose up -d
sleep 60
docker inspect --format '{{.State.Health.Status}}' uptime-kuma
curl -sS https://<DOMAIN>/setup-database-info
echo
curl -sSL https://<DOMAIN>/ | grep -ci 'uptime kuma'
```

Assert, all three: `docker inspect` prints `healthy`, the JSON line contains `"needSetup":false`
because step 2 already chose SQLite, and the last prints a number greater than `0`. Print what
you received for each. If health is `starting`, wait 60 seconds and check again. If anything
still misses, stop, run `docker compose logs --tail 40 uptime-kuma`, and name the likely
earlier step. A running container is not success.

The first screen at https://<DOMAIN> is a form asking for a username and a password to create
the administrator account. Until it is submitted, anyone who loads that page can submit it.

STOP: tell the user to open https://<DOMAIN> right now, create the administrator account, and
save the password in their password manager. Wait until they confirm.

Then have them prove it closed: ask them to open https://<DOMAIN> in a private window and
confirm they see a sign-in form and no create-account fields. Assert: they confirm that in
words. Do not report success on the strength of the container being up.

## 8. First backup and restore

Take the backup now, before the user adds a monitor. Stop first: a SQLite file copied mid-write
is not a backup.

```bash
cd /srv/uptime-kuma
docker compose stop
sudo tar -C /srv/uptime-kuma -czf /srv/uptime-kuma/backups/uptime-kuma-$(date +%F).tar.gz data
docker compose start
ls -lh /srv/uptime-kuma/backups/
```

Assert: the archive exists and is non-empty. Print its size. `data` is the whole install: there
is no `.env` here, and `data/kuma.db` holds the monitors, the account and every heartbeat ever
recorded. A backup on the same disk is not a backup, so run this from the user's machine:

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

To restore: `docker compose down`, `sudo rm -rf /srv/uptime-kuma/data`,
`sudo tar -C /srv/uptime-kuma -xzf` the archive, then `docker compose up -d`. Those four
commands are the whole disaster plan. Tell the user that heartbeat history is kept forever by
default, so this archive grows with the number of monitors times the check interval, and the
retention setting in the interface is the lever if the disk starts filling.

## 9. Updating later

New versions are at https://github.com/louislam/uptime-kuma/releases. Take a backup first, then
edit the image line in /srv/uptime-kuma/compose.yml to the new tag and digest. Uptime Kuma
migrates its own database on the next boot, so wait for the health check to go green before
calling this done.

```bash
cd /srv/uptime-kuma
docker compose pull
docker compose up -d
docker compose logs --tail 20 uptime-kuma
```

## 10. What will probably go wrong

The alert that never arrives. I set up a monitor, watched it go green, and assumed the whole
thing worked, including the notification channel I had configured and never fired. It had a
typo in the webhook URL, and I found out three weeks later when a real outage produced silence.
Tell the user to do this on day one, not later: point a second monitor at a hostname that does
not exist, wait for it to go red, and confirm the alert lands on their phone. An untested alert
channel is not an alert channel, and this failure is invisible until the day it matters.

## 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 configure MariaDB. `db-config.json` picks SQLite, which is why this is one container.
- Do not configure notification channels. Every one of them is an account or a token somewhere
  else, and the user picks those in the interface.
- Do not publish 3001 on the host or open it in the firewall. Caddy is the only way in.

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 Uptime Kuma 2.5.0 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.

One thing to sit with before you start: a monitor running on this server cannot tell you when
this server is down. If you have a second machine anywhere, this belongs on that one, and you
should keep a free external check pointed at whichever box ends up hosting it.

## 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>
```

You should see: at least `512` MB available, at least `5` G free, `amd64` or `arm64`, and your
server's IP address on the last line.

If you do not: an empty last line means the A record does not exist yet. Add it at your DNS
provider, wait a minute, and run `dig +short <DOMAIN>` again. Caddy cannot get a certificate
for a hostname that does not resolve, and failed attempts count against a rate limit you cannot
see.

## 2. Layout

The image runs as the `node` user, uid 1000, so `data` belongs to 1000 and not to you. The
`db-config.json` written here is what picks the database: with that file in place Uptime Kuma
uses SQLite and never shows you its database setup screen.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/uptime-kuma /srv/uptime-kuma/backups
sudo install -d -m 750 -o 1000 -g 1000 /srv/uptime-kuma/data
printf '{\n    "type": "sqlite"\n}\n' | sudo tee /srv/uptime-kuma/data/db-config.json >/dev/null
sudo chown 1000:1000 /srv/uptime-kuma/data/db-config.json
ls -la /srv/uptime-kuma/data
```

You should see: `db-config.json` owned by `1000`, a few dozen bytes.

If you do not: a file owned by `root` means the `chown` line did not run, and the container
will refuse to write beside it. Run that line again on its own. This directory has to be on
local disk: SQLite needs real POSIX file locks, and a network mount corrupts the database
quietly, weeks later.

## 3. Secrets

There is nothing to generate and no `.env` file. Uptime Kuma has one credential, the
administrator account, and you create it in a browser at step 7.

Between the container starting and that account existing, the setup form is open to whoever
reaches your hostname first. Step 7 is written to make that window short, which is why it asks
you to stop reading and go create the account the moment the checks pass.

Nothing in this guide asks you to paste a credential into this chat window. Do not paste the
administrator password, or the output of any command containing it, at any point.

## 4. compose.yml

Paste the whole block at once, including the last two lines.

```bash
cat > /srv/uptime-kuma/compose.yml <<'EOF'
# Uptime Kuma · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   compose shape ...... https://github.com/louislam/uptime-kuma/blob/master/compose.yaml
#   install notes ...... https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install
#   reverse proxy ...... https://github.com/louislam/uptime-kuma/wiki/Reverse-Proxy
#
# One container. There is no Caddy service here: Prompt Zero already runs Caddy
# under systemd on the host, and a second one in a container would fight it for
# 80 and 443. Upstream pins the floating `2` tag and publishes 3001 on every
# interface; this file pins the exact release and binds to loopback instead. The
# image runs as the node user (uid 1000), hence the ownership in step 2. Tag and
# digest are the 2.5.0 release read from Docker Hub on 2026-08-05, for
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.0@sha256:a8610b3b4c38077922ba51b036691e06887d7cefd91fe620fd3d6d23d03dc240
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      # kuma.db and db-config.json both live here. Local disk only: SQLite
      # needs real POSIX file locks, and a network mount corrupts it quietly.
      - /srv/uptime-kuma/data:/app/data
    ports:
      # Loopback only. The Caddy that Prompt Zero installed on the host is the
      # only thing that can reach this port, and 8091 never enters the firewall.
      - "127.0.0.1:8091:3001"
EOF
cd /srv/uptime-kuma && docker compose config >/dev/null && echo "compose OK"
```

You should see: `compose OK` and nothing else.

If you do not: `services must be a mapping` means the indentation was lost between the page and
your terminal. Run `rm /srv/uptime-kuma/compose.yml` and paste the block again in one go.

If you have seen an Uptime Kuma compose file elsewhere with a `caddy` service in it, do not
merge the two. Caddy is already running under systemd on this box, and a container claiming 80
and 443 would fail to start and take every other site with it.

## 5. Caddy and TLS

This appends one site block to the Caddy config Prompt Zero installed. Replace `<DOMAIN>` in
the block with your hostname before you paste. The first line takes a copy, because a syntax
error here takes down every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-uptime-kuma
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Uptime Kuma · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://github.com/louislam/uptime-kuma/wiki/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
	}

	# The dashboard is a WebSocket application. Caddy negotiates the upgrade on
	# its own, so there are no Upgrade or Connection headers to set by hand,
	# which is the step every nginx guide spends a paragraph on.
	#
	# 8091 is the loopback port compose publishes; it is never in the firewall.
	reverse_proxy 127.0.0.1:8091
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

You should see: `Valid configuration` from validate, and no output at all from reload.

If you do not: run `sudo cp /etc/caddy/Caddyfile.before-uptime-kuma /etc/caddy/Caddyfile`,
reload, and paste again, checking that the blank line from the second command really landed.
Caddy asks Let's Encrypt for the certificate on the first request to your hostname and renews
it on its own, so there is nothing to schedule.

## 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/tcp`, `443/tcp` and `443/udp`, and no rule
mentioning `8091` or `3001`.

If you do not: a rule for either port from an earlier attempt should go, with
`sudo ufw delete allow 3001`. 8091 is bound to 127.0.0.1 by the compose file, so nothing
outside the machine can reach it and a firewall rule for it would cover traffic that cannot
arrive.

## 7. Start and verify

The image's own health check allows a three-minute start period, so the first boot is slower
than you expect. That is not a failure.

```bash
cd /srv/uptime-kuma
docker compose pull
docker compose up -d
sleep 60
docker inspect --format '{{.State.Health.Status}}' uptime-kuma
curl -sS https://<DOMAIN>/setup-database-info
echo
curl -sSL https://<DOMAIN>/ | grep -ci 'uptime kuma'
```

You should see: `healthy`, then a line of JSON containing `"needSetup":false`, then a number
greater than `0`.

If you do not: `starting` is not a failure yet, so wait 60 seconds and run the `docker inspect`
line again. `"needSetup":true` means `db-config.json` did not take, so go back to step 2 and
check its ownership. `000` or `502` from curl means the certificate is not there yet, so run
`sudo journalctl -u caddy -n 30`.

A container listed in `docker ps` is not proof of anything. The three checks above are.

Now open https://<DOMAIN> and create your administrator account. Do it before you make coffee:
until it exists, anyone who loads that page can create it instead. Then open the same URL in a
private window.

You should see: a sign-in form, with no create-account fields.

If you do not: a create-account form in the private window means your account was not saved.
Go back and finish it before you do anything else.

## 8. First backup and restore

Do this before you add a monitor, so you find out now whether it works. The stop matters: a
SQLite file copied mid-write is not a backup.

```bash
cd /srv/uptime-kuma
docker compose stop
sudo tar -C /srv/uptime-kuma -czf /srv/uptime-kuma/backups/uptime-kuma-$(date +%F).tar.gz data
docker compose start
ls -lh /srv/uptime-kuma/backups/
```

You should see: one `.tar.gz` file, a few hundred kilobytes on a fresh install.

If you do not: `tar: data: Cannot open` means the `cd` did not happen. A size of `45` bytes
means tar wrote an empty archive because the paths were wrong, so check
`sudo ls /srv/uptime-kuma/data` before you trust it.

A backup on the same disk as the data is not a backup. Run this one on your own machine, not on
the server:

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

You should see: one file copied, and the same file listed by `ls -lh ~/backups/uptime-kuma/`.

If you do not: `Permission denied (publickey)` means you ran it on the server by mistake. The
`vps:` prefix only means something on your own machine.

Now prove the restore, because a backup you have never restored is a guess:

```bash
cd /srv/uptime-kuma
docker compose down
sudo rm -rf /srv/uptime-kuma/data
sudo tar -C /srv/uptime-kuma -xzf /srv/uptime-kuma/backups/uptime-kuma-$(date +%F).tar.gz
docker compose up -d
```

You should see: `Created` and `Started`, then after a minute a sign-in page at https://<DOMAIN>
that still accepts your administrator account.

If you do not: a page that has turned back into a create-account form means the archive did not
contain `data/kuma.db`. Stop and go back to the tar step. Those four commands are the whole
disaster plan, and you have now run them once.

Heartbeat history is kept forever by default, so this archive grows with the number of monitors
times how often they check. On a small disk that is the thing that fills it, and the retention
setting in the interface is the lever.

## 9. Updating later

New versions are at https://github.com/louislam/uptime-kuma/releases. Take a backup first, then
edit the `image:` line in /srv/uptime-kuma/compose.yml to the new tag and its digest.

```bash
cd /srv/uptime-kuma
docker compose pull
docker compose up -d
docker compose logs --tail 20 uptime-kuma
```

You should see: `Recreated`, then startup and migration lines, then no repeating restart.

If you do not: put the old tag and digest back and run the same three commands. Uptime Kuma
migrates its own database on the next boot, so wait for
`docker inspect --format '{{.State.Health.Status}}' uptime-kuma` to print `healthy` before you
call the update done.

## 10. What will probably go wrong

The alert that never arrives. I set up a monitor, watched it go green, and assumed the whole
thing worked, including the notification channel I had configured and never fired. It had a
typo in the webhook URL, and I found out three weeks later when a real outage produced silence.
Do this on day one: point a second monitor at a hostname that does not exist, wait for it to go
red, and confirm the alert lands on your phone. An untested alert channel is not an alert
channel, and this failure is invisible until the day it matters.

## 11. Out of scope

- Do not add a Caddy container to the compose file. Caddy already runs under systemd here.
- Do not configure MariaDB. `db-config.json` picks SQLite, which is why this is one container.
- Do not configure notification channels while installing. Each is an account or a token
  somewhere else, and you pick those in the interface afterwards.
- Do not publish 3001 on the host or open it in the firewall. Caddy is the only way in.

299 lines · 14,989 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 Uptime Kuma 2.5.0 on this computer, reachable at http://localhost:8091 from this
computer and nowhere else, with everything it keeps under ~/selfhost/uptime-kuma/.

## 1. Preflight

Find out which operating system this is first. Steps 2, 3 and 8 branch on it.

```bash
uname -s
case "$(uname -s)" in
  Darwin) sysctl -n hw.memsize | awk '{printf "%d MB of RAM installed\n", $1/1048576}' ;;
  Linux) free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}' ;;
  MINGW*|MSYS*) powershell -Command "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory" ;;
esac
df -h ~
```

`Darwin` is macOS, `Linux` is Linux, and `MINGW` or `MSYS` is Windows under Git Bash.

Uptime Kuma needs 512 MB of RAM and 5 GB free on the home disk. The 2.5.0 image covers amd64
and arm64, so Apple Silicon and Intel are both fine.

Free disk under 5 GB is a stop on any OS. For RAM, only the Linux line measures the floor:
under 512 MB available, print both numbers and stop. macOS and Windows print installed RAM
instead (bytes on Windows, divide by 1048576), which any machine running Docker Desktop clears;
there the 512 MB applies to Docker Desktop's own allocation, so have the user check Settings,
Resources and stop if it shows less. Do not install and hope.

Say this to the user before installing anything, with nothing left out. A monitor on a machine
that sleeps is a monitor that sleeps: when the lid closes the checks stop and nothing is
watching until it wakes. This computer also cannot alert them that it is itself off: a monitor
that is down produces the same silence as one with nothing to report. If they want checks that
keep running overnight, this belongs on a machine that stays on, with one free external check
pointed at it. That is not a reason to stop, it is what they are choosing.

## 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:

```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
```

  Say one sentence to the user: membership of the `docker` group is root-equivalent on this
  machine, and the group change lands at their next login, so they may need to log out first.
- 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

Everything lives in one directory under the home directory. `db-config.json` is written before
the first boot because it picks the database: with that file present Uptime Kuma uses SQLite
and skips its database setup screen.

```bash
mkdir -p ~/selfhost/uptime-kuma/data ~/selfhost/uptime-kuma/backups
printf '{\n    "type": "sqlite"\n}\n' > ~/selfhost/uptime-kuma/data/db-config.json
ls -la ~/selfhost/uptime-kuma/data
```

On Linux only, `./data` is a real directory on the real filesystem and the image runs as uid
1000, so hand it over:

```bash
sudo chown -R 1000:1000 ~/selfhost/uptime-kuma/data
```

Do not run that on macOS or Windows. Docker Desktop runs the engine in a virtual machine and
rewrites ownership across its file share, so the container already sees itself as the owner and
a host `chown` changes nothing it can observe.

Assert: `ls -la` lists `db-config.json`, and on Linux it belongs to `1000` after the chown.
Keep this directory on the local disk and out of any folder a sync service watches: SQLite
needs real POSIX file locks, and a synced or networked folder corrupts it quietly, weeks
later. Backups are the exception, and step 8 uses one.

## 4. Secrets

Nothing is generated here and there is no `.env` file. Uptime Kuma's only credential is the
administrator account, and the user creates it in a browser at step 7, so this block runs no
commands.

Say two things to the user. First: between the container starting and that account existing,
the setup form is open to anyone with a session on this computer, which is why step 7 makes
that window short and stops there. Second, on Windows: mode bits on NTFS are advisory, so no
`chmod` protects anything here; their own account is the real boundary on a single-user
machine, and everything this install writes sits in their home directory.

## 5. compose.yml

```bash
cat > ~/selfhost/uptime-kuma/compose.yml <<'EOF'
# Uptime Kuma · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   compose shape ...... https://github.com/louislam/uptime-kuma/blob/master/compose.yaml
#   install notes ...... https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install
#   image details ...... https://github.com/louislam/uptime-kuma/blob/master/docker/dockerfile
#
# One container, on the computer the user is sitting at. No Caddy and no
# certificate: nothing outside this machine can reach 8091, so there is nothing
# to certify. This file sits in ~/selfhost/uptime-kuma/ and its paths are
# relative to it, which is what lets one file work on macOS, Linux and Windows.
# Upstream pins the floating `2` tag and publishes 3001 on every interface; this
# file pins the release and binds to loopback. The image runs as the node user
# (uid 1000), hence the Linux-only chown in step 3. Tag and digest are the 2.5.0
# release read from Docker Hub on 2026-08-05, for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.0@sha256:a8610b3b4c38077922ba51b036691e06887d7cefd91fe620fd3d6d23d03dc240
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      # kuma.db and db-config.json live here. Local disk only: SQLite needs real
      # POSIX file locks, so a network mount or a synced folder corrupts it.
      - ./data:/app/data
    ports:
      # Loopback only. No other device on this network can reach 8091, not even
      # the user's phone.
      - "127.0.0.1:8091:3001"
EOF
cd ~/selfhost/uptime-kuma && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. The container serves 3001 inside itself; 8091 is the host
port bound to 127.0.0.1, the same one the server path uses.

## 6. Nothing is public

Nothing here is reachable from outside this computer, and no step in this prompt changes that.

- The published port is `127.0.0.1:8091`, which means this machine only. Another laptop on the
  same wifi cannot reach it, and neither can the user's phone. That is this path, not a defect
  in it.
- No domain, no DNS record to wait for, no certificate to issue, no firewall rule to add: there
  is no hostname to certify and nothing listening on an address another machine could route to.
  The server path's DNS wait, TLS step and ufw block all fall away.
- Browsers treat `http://localhost` as a secure context, so the dashboard works over plain HTTP
  without the warnings a real hostname would earn.
- This install sets no base URL and the compose file carries no hostname. If the user later
  fills a base-URL field, http://localhost:8091 is the only value that resolves here, and links
  built from it are dead on every other device.
- The checks go out from this computer, over whatever network it is on. A site that is up for
  everyone else but blocked on this cafe wifi is recorded as down: a true answer to a narrower
  question than a rented server answers.

## 7. Start and verify

The image carries a health check with a three-minute start period, so the first boot takes
longer than it looks like it should. That is not a failure yet.

```bash
cd ~/selfhost/uptime-kuma
docker compose pull
docker compose up -d
sleep 60
docker inspect --format '{{.State.Health.Status}}' uptime-kuma
curl -sS http://localhost:8091/setup-database-info
echo
curl -sSL http://localhost:8091/ | grep -ci 'uptime kuma'
```

Assert, all three: `docker inspect` prints `healthy`, the JSON line contains `"needSetup":false`
because step 3 chose SQLite, and the last command prints a number greater than `0`.
Print what you received for each. If health is `starting`, wait 60 seconds and check again. If
anything still misses, stop, run `docker compose logs --tail 40 uptime-kuma`, and name the
earlier step that likely caused it. A running container is not success.

The first screen at http://localhost:8091 is a form asking for a username and password to
create the administrator account. Until it is submitted, anyone at this computer can submit it.

STOP: tell the user to open http://localhost:8091 now, create the administrator account, and
save the password in their password manager. Wait until they confirm.

Then have them prove it closed: ask them to open http://localhost:8091 in a private window and
confirm a sign-in form with no create-account fields. Assert: they confirm that in words. Do
not report success on the container being up.

## 8. First backup and restore

Take the backup now, before the user adds a monitor. Stop the container first: a SQLite file
copied mid-write is not a backup.

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

Assert: `ls -lh` shows the archive non-empty, and `tar -tzf` on it lists `data/kuma.db`. Print
its size. On Linux, if `tar` prints `Cannot open: Permission denied`, the login user is not uid
1000 and step 3 handed `data` to 1000: rerun the line with `sudo` and tell the user the archive
belongs to root.

`data` is the whole install: no `.env` here, and `data/kuma.db` holds the monitors, the
administrator account and every heartbeat ever recorded.

A backup on the same disk as the data is not a backup, and on one computer the disk and the
machine fail together. Get a copy off this machine now, and ask first: which folder does a sync
service already watch, iCloud Drive, OneDrive, Dropbox, Syncthing? If they sync nothing, have
them plug in a USB stick, under /Volumes on macOS, usually /media on Linux, a drive letter such
as /d in Git Bash. Confirm the answer with `ls -d` on it, then `cp` the archive there and print
the result. Do not guess a path: `~/Dropbox` is absent on most machines and the copy fails.

To restore, run `ls -lh backups/`, have the user name the archive, and put that exact filename
in both `ARCHIVE` slots. Nothing is deleted until `tar -tzf` has read the archive through, so a
wrong name costs a message, not the install:

```bash
cd ~/selfhost/uptime-kuma
tar -tzf backups/ARCHIVE >/dev/null && docker compose down && rm -rf data && tar -xzf backups/ARCHIVE && docker compose up -d
```

That one line is the whole disaster plan. On Linux, if step 3's chown ran against a login user
that is not uid 1000, the `rm -rf` and the `tar` need `sudo` too. Tell the user that heartbeat
history is kept forever by default, so this archive grows with the monitor count times the
check interval; the retention setting is the lever if the disk fills.

## 9. Updating later

New versions are listed at https://github.com/louislam/uptime-kuma/releases. Take a backup
first, then edit the image line in ~/selfhost/uptime-kuma/compose.yml to the new tag and
digest. Uptime Kuma migrates its own database on the next boot, so wait for the health check to
go green before calling this done.

```bash
cd ~/selfhost/uptime-kuma
docker compose pull
docker compose up -d
docker compose logs --tail 20 uptime-kuma
```

## 10. What will probably go wrong

Docker Desktop, after a reboot. The compose file says `restart: unless-stopped`, and I read
that as a promise the container comes back on its own. It does not on macOS or Windows: nothing
comes back until Docker Desktop itself is running, and it starts at sign-in, sometimes only
when the user opens it. I rebooted, went to lunch, and came back to a dashboard missing two
hours with no error anywhere in it, because a monitor that was not running produces the same
silence as one with nothing to report. Tell the user to turn on Docker Desktop's
start-at-login setting, and to read any flat gap in the graphs as this until ruled out.

## 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 configure MariaDB. `db-config.json` picks SQLite, which is why this is one container.
- Do not configure notification channels. Each one is an account or a credential somewhere
  else, and the user picks those in the interface afterwards.
- Do not rebind 8091 to this machine's network address so a phone can reach the dashboard. That
  puts a sign-in page on every network this computer joins, in exchange for a glance.

# Uptime Kuma · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   compose shape ...... https://github.com/louislam/uptime-kuma/blob/master/compose.yaml
#   install notes ...... https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install
#   image details ...... https://github.com/louislam/uptime-kuma/blob/master/docker/dockerfile
#
# One container, on the computer the user is sitting at. No Caddy and no
# certificate: nothing outside this machine can reach 8091, so there is nothing
# to certify. This file sits in ~/selfhost/uptime-kuma/ and its paths are
# relative to it, which is what lets one file work on macOS, Linux and Windows.
# Upstream pins the floating `2` tag and publishes 3001 on every interface; this
# file pins the release and binds to loopback. The image runs as the node user
# (uid 1000), hence the Linux-only chown in step 3. Tag and digest are the 2.5.0
# release read from Docker Hub on 2026-08-05, for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.0@sha256:a8610b3b4c38077922ba51b036691e06887d7cefd91fe620fd3d6d23d03dc240
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      # kuma.db and db-config.json live here. Local disk only: SQLite needs real
      # POSIX file locks, so a network mount or a synced folder corrupts it.
      - ./data:/app/data
    ports:
      # Loopback only. No other device on this network can reach 8091, not even
      # the user's phone.
      - "127.0.0.1:8091:3001"