Can I self-host Uptime.com?

328 lines · 14,920 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 Kener 4.1.2 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, and the same hostname becomes `ORIGIN` in
step 3.

Say two things to the user before anything installs. One: a monitor cannot tell them that the
machine it runs on is down, so this belongs on a box other than the ones it watches, and they
should keep one free external check pointed at this hostname from a service they do not run.
Two: what goes on that hostname is a public status page. It answers everybody by design, and
every monitor name and description they add later is published to whoever loads it. The manage
screens behind it are not public, and step 7 closes the one window where that is not yet true.

Kener needs 1024 MB of RAM available and 5 GB free on /srv. Both images publish amd64 and
arm64. Measure all four:

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

## 2. Layout

Three directories, three owners, and the ownership is the part that matters. The Kener image
runs as the `node` user, uid 1000, so it cannot write a directory owned by the login user. The
redis image chowns its own data directory on first start, so that one is left to root.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/kener /srv/kener/backups
sudo install -d -m 750 -o 1000 -g 1000 /srv/kener/database
sudo install -d -m 750 /srv/kener/redis
ls -la /srv/kener
```

Assert: `ls -la` shows `backups` owned by the login user, `database` owned by `1000`, and
`redis` owned by root. Nothing is written outside /srv/kener. Keep `database` on local disk:
`kener.sqlite.db` is a SQLite file and a network mount corrupts one quietly, weeks later.

## 3. Secrets

One secret, `KENER_SECRET_KEY`. Upstream documents it as the key that signs the session tokens
and encrypts stored credentials, and documents `openssl rand -base64 32` as the way to make
one. Generate it on the server. Do not print it, do not repeat it in your summary, and do not
put it in any log line.

`ORIGIN` goes in the same file and is not a secret. It is the public URL SvelteKit compares
against on every form post, with no trailing slash, and step 10 is what happens when it is
wrong.

```bash
umask 077
cat > /srv/kener/.env <<EOF
ORIGIN=https://<DOMAIN>
TZ=UTC
KENER_SECRET_KEY=$(openssl rand -base64 32)
EOF
chmod 600 /srv/kener/.env
umask 022
ls -l /srv/kener/.env
```

Assert: the file exists with mode `-rw-------`, and `ORIGIN` reads `https://` followed by the
real hostname. Tell the user the key is in /srv/kener/.env, that they can read it themselves
with `sudo grep KENER_SECRET_KEY /srv/kener/.env`, and that changing it later signs everyone
out and makes anything Kener had encrypted with it unreadable, so it belongs in their password
manager today.

## 4. compose.yml

```bash
cat > /srv/kener/compose.yml <<'EOF'
# Kener · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   deployment ......... https://kener.ing/docs/v4/setup/deployment
#   environment ........ https://kener.ing/docs/v4/setup/environment-variables
#   database ........... https://kener.ing/docs/v4/setup/database-setup
#   image build ........ https://github.com/rajnandan1/kener/blob/v4.1.2/Dockerfile
#
# Two services. Redis is not optional in v4: upstream's own compose file calls
# it required for the queues, the cache and the scheduler, and the environment
# reference marks REDIS_URL required, so a Kener with no Redis runs no checks.
# No database container: DATABASE_URL is left unset, so upstream defaults to
# SQLite at ./database/kener.sqlite.db, the mount below. The image runs as the
# node user, uid 1000, which is why step 2 hands database/ to 1000. Digests
# read from the registries on 2026-08-07; both images publish amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  redis:
    image: redis:7.4.10-alpine@sha256:e7723ff73d963f5cc6d9c4643ea3d989527a402a319239054e9472a7fb9219a2
    container_name: kener-redis
    restart: unless-stopped
    volumes:
      # Queue and scheduler state only: monitors, incidents and every result
      # live in the SQLite file below. The image chowns this on first start.
      - /srv/kener/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    # No `ports:` at all: 6379 is reachable only from the other container.

  kener:
    image: ghcr.io/rajnandan1/kener:v4.1.2@sha256:239ab635b900b3fe0a4e22f5599f77525211d1b7a25b8fcf3d173936ddacc1cc
    container_name: kener
    restart: unless-stopped
    env_file: /srv/kener/.env
    environment:
      # Redis is on the compose network only, so this carries no credential.
      REDIS_URL: redis://redis:6379
      NODE_ENV: production
    volumes:
      # kener.sqlite.db: every monitor, incident, page, user and result.
      - /srv/kener/database:/app/database
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8179.
      - "127.0.0.1:8179:3000"
    depends_on:
      redis:
        condition: service_healthy
EOF
cd /srv/kener && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. Two services, one published port. Do not add a Postgres
service: `DATABASE_URL` is unset on purpose, upstream then uses SQLite in the mounted
`database` directory, and that one file is what step 8 backs up.

## 5. Caddy and TLS

Append the block below to the Caddyfile Prompt Zero installed, with `<DOMAIN>` replaced by the
real hostname. Copy the file first: a syntax error here takes down every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-kener
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Kener · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://kener.ing/docs/v4/setup/deployment 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. That same hostname is
# ORIGIN in .env: Kener hands ORIGIN to SvelteKit for the cross-site check on
# every form post, so if the two disagree the page loads and the sign-in fails.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		# The status page is public and the manage screens behind it are not,
		# and both share a hostname. SAMEORIGIN protects the second, at the cost
		# of the badge embeds Kener offers for other people's sites.
		X-Frame-Options "SAMEORIGIN"
		# Upstream reads the Origin header when the browser sends one and falls
		# back to SameSite=Lax cookies when it does not, so this costs nothing.
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8179 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:8179
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Assert: `caddy validate` exits 0 and the reload exits 0. If validate fails, restore
/etc/caddy/Caddyfile.before-kener, 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. 8179 stays closed because compose binds it to 127.0.0.1, and 6379 stays
closed because compose never publishes it, so Redis has no host port a rule could apply to. The
checks are outbound and need nothing opened. Assert: `ufw status verbose` prints
`Status: active`, shows 80, 443/tcp and 443/udp, and no rule mentioning 8179, 6379 or 3000.

## 7. Start and verify

Kener runs its migrations and its seed on the way up, so the first boot writes the schema and a
starter status page before it answers anything. Use the loop, not a fixed sleep.

```bash
cd /srv/kener
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>/healthcheck?strict=1'); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS https://<DOMAIN>/healthcheck; echo
curl -sSL https://<DOMAIN>/ | grep -c 'Service Status'
curl -sS -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/api/v1/monitors
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Create Admin Account'
```

Assert all five, and print what you received for each. The loop ends printing `200`, and it
asks with `?strict=1` on purpose: upstream answers `200` from `/healthcheck` even when a
dependency is down, and only the strict form turns that into `503`. The plain call then prints
`{"status":"ok","db":true,"redis":true}`, and all three fields matter. The third command prints
a number greater than `0`, because `Service Status` is the heading the seeded status page
renders. The API call prints `401`, upstream's answer to a request carrying no bearer token,
and that is the security assert in this block. The last prints a number greater than `0`,
because with no users yet the sign-in page is a `Create Admin Account` form. If any of the five
misses, stop, run `docker compose logs --tail 40 kener`, then
`docker compose logs --tail 20 redis`, and name the likely earlier step: a Redis that never
reports healthy holds the app in `depends_on` and points at step 4, and a 502 from Caddy with
both containers up points at step 5. A running container is not success.

That `Create Admin Account` form is open to whoever loads the hostname first. Close it now.

STOP: tell the user to open https://<DOMAIN>/account/signin, fill in a name, an email address
and a password to create the administrator account, and save that password in their password
manager. Wait. Do not continue until they confirm.

Once they confirm, prove the window is shut:

```bash
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Create Admin Account'
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Sign In'
```

Assert: the first prints `0` and the second prints a number greater than `0`. Upstream's signup
action refuses once one user exists, so that page is a login form from here on. Both asserts
must pass before you report success.

## 8. First backup and restore

One archive: the SQLite database, the environment file, the compose file and the live Caddy
site block. Redis is not in it, because it holds queue and scheduler state that rebuilds
itself, while every monitor, incident, page, user and result is in the SQLite file.

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

Assert: the archive exists and is non-empty. Print its size. The containers are stopped on
purpose and downtime is a few seconds, because a SQLite file copied mid-write is not a backup.

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/kener
scp vps:/srv/kener/backups/*.tar.gz ~/backups/kener/
```

To restore: `docker compose down`, `sudo rm -rf /srv/kener/database`, recreate that directory
as in step 2, untar the archive back into /srv/kener, put the Caddy block back if that is what
was lost, then `docker compose up -d`. Tell the user what the archive holds in plain terms:
`database/kener.sqlite.db` is their monitors, their incident history and their administrator
account, and `.env` is the key that decrypts what Kener stored under it, so the two are worth
nothing apart.

## 9. Updating later

New versions are listed at https://github.com/rajnandan1/kener/releases. The release tag and
the image tag are the same string, so release `v4.1.3` is image tag `v4.1.3`. Take a backup
first, then edit the image line in /srv/kener/compose.yml to the new tag and its digest:

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

Kener runs its migrations on the way up, so watch that log until it settles, then re-run step
7's health check and the `Service Status` grep before calling the update done.

## 10. What will probably go wrong

The sign-in that fails on a page that loads. I had `ORIGIN` set with a trailing slash, and
everything else looked right: the status page rendered, the health check said ok, the
`Create Admin Account` form appeared. Submitting it returned a bare
`Cross-site POST form submissions are forbidden`, and I spent twenty minutes in Caddy's logs
looking for a problem that was one character in .env. Kener hands `ORIGIN` to SvelteKit, which
compares it against the host the browser used on every form post; a trailing slash, an `http://`
where the browser said `https://`, or a `www.` on one side only are all mismatches. If step 7's
STOP will not complete, run `grep ORIGIN /srv/kener/.env` first, fix it, then
`docker compose up -d --force-recreate` before touching anything else.

## 11. Out of scope

- Do not set `DATABASE_URL` and do not add a Postgres or MySQL service. SQLite is the choice
  here, and it is why the whole install is one directory and one file to copy.
- Do not configure SMTP, `RESEND_API_KEY`, or any alerting provider. Every one of them is an
  account or a key somewhere else, and the user wires those up in the manage screens.
- Do not set `KENER_BASE_PATH` and do not switch to a `-status` image variant. Those exist for
  serving Kener under a subpath of a hostname that already has a site, and they are a different
  image built at a different base path.
- Do not publish 3000 or 6379 on the host and do not open either in the firewall. Caddy is the
  only way in, and Redis is reachable only from the other container.

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 Kener 4.1.2 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 two before step 1, because together they decide whether you want this at all. A
monitor cannot tell you that the machine it runs on is down, so this belongs on a box other
than the ones it watches, and you should keep one free external check pointed at this hostname
from a service you do not run. And what you are building is a public status page: the dashboard
answers everybody by design, and every monitor name and description you add later is published
to whoever loads it. The sign-in and manage screens behind it are not public, and step 7 closes
the one window where that distinction does not yet hold.

## 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 `1024` MB available, at least `5` G free, `amd64` or `arm64`, and your
server's IP on the last line.

If you do not: an empty last line means the A record does not exist yet. Add it, wait a minute,
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. Pick that hostname
carefully for a second reason too: it becomes `ORIGIN` in step 3, the address Kener compares
every form post against, so changing it later means editing .env and restarting.

## 2. Layout

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/kener /srv/kener/backups
sudo install -d -m 750 -o 1000 -g 1000 /srv/kener/database
sudo install -d -m 750 /srv/kener/redis
ls -la /srv/kener
```

You should see: `backups` owned by you, `database` owned by `1000`, and `redis` owned by
`root`.

If you do not: those three owners are deliberate and none of them is you by accident. The Kener
image runs as its own `node` user, uid 1000, so a `database` directory owned by your login user
is one the container cannot write, and the first boot fails with a permission error about
`kener.sqlite.db`. The redis image chowns its own data directory the first time it starts, so
leaving `redis` to root is correct. Keep `/srv/kener/database` on the server's local disk: it
is a SQLite file, and a network mount corrupts one quietly, weeks later.

## 3. Secrets

One secret here, `KENER_SECRET_KEY`. Upstream documents it as the key that signs your session
tokens and encrypts stored credentials, and documents `openssl rand -base64 32` as the way to
make one. It is generated on the server and written straight into a file only you can read.
`ORIGIN` sits in the same file and is not a secret: it is the public URL SvelteKit compares
against on every form post, and it takes no trailing slash.

```bash
umask 077
cat > /srv/kener/.env <<EOF
ORIGIN=https://<DOMAIN>
TZ=UTC
KENER_SECRET_KEY=$(openssl rand -base64 32)
EOF
chmod 600 /srv/kener/.env
umask 022
ls -l /srv/kener/.env
```

You should see: mode `-rw-------`, your own username twice, and the path. Replace `<DOMAIN>` on
the first line with your real hostname before you paste.

If you do not: a mode of `-rw-r--r--` means `umask 077` did not take effect, which happens if
you pasted the lines separately in different shells. Run `chmod 600 /srv/kener/.env` and carry
on. If the file already existed from an earlier attempt, this block has now replaced the key,
which is harmless before anyone has signed in and disruptive afterwards: a new key invalidates
every session and makes anything Kener encrypted under the old one unreadable.

Do not paste that file, the key, or any command output containing it into this chat window.
Read the key once with `sudo grep KENER_SECRET_KEY /srv/kener/.env`, put it in your password
manager, and close the terminal scrollback if you share screenshots.

## 4. compose.yml

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

```bash
cat > /srv/kener/compose.yml <<'EOF'
# Kener · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   deployment ......... https://kener.ing/docs/v4/setup/deployment
#   environment ........ https://kener.ing/docs/v4/setup/environment-variables
#   database ........... https://kener.ing/docs/v4/setup/database-setup
#   image build ........ https://github.com/rajnandan1/kener/blob/v4.1.2/Dockerfile
#
# Two services. Redis is not optional in v4: upstream's own compose file calls
# it required for the queues, the cache and the scheduler, and the environment
# reference marks REDIS_URL required, so a Kener with no Redis runs no checks.
# No database container: DATABASE_URL is left unset, so upstream defaults to
# SQLite at ./database/kener.sqlite.db, the mount below. The image runs as the
# node user, uid 1000, which is why step 2 hands database/ to 1000. Digests
# read from the registries on 2026-08-07; both images publish amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  redis:
    image: redis:7.4.10-alpine@sha256:e7723ff73d963f5cc6d9c4643ea3d989527a402a319239054e9472a7fb9219a2
    container_name: kener-redis
    restart: unless-stopped
    volumes:
      # Queue and scheduler state only: monitors, incidents and every result
      # live in the SQLite file below. The image chowns this on first start.
      - /srv/kener/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    # No `ports:` at all: 6379 is reachable only from the other container.

  kener:
    image: ghcr.io/rajnandan1/kener:v4.1.2@sha256:239ab635b900b3fe0a4e22f5599f77525211d1b7a25b8fcf3d173936ddacc1cc
    container_name: kener
    restart: unless-stopped
    env_file: /srv/kener/.env
    environment:
      # Redis is on the compose network only, so this carries no credential.
      REDIS_URL: redis://redis:6379
      NODE_ENV: production
    volumes:
      # kener.sqlite.db: every monitor, incident, page, user and result.
      - /srv/kener/database:/app/database
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8179.
      - "127.0.0.1:8179:3000"
    depends_on:
      redis:
        condition: service_healthy
EOF
cd /srv/kener && docker compose config >/dev/null && echo "compose OK"
```

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

If you do not: `env file /srv/kener/.env not found` means step 3 did not write the file.
`services must be a mapping` means the indentation was lost between the page and your terminal:
run `rm /srv/kener/compose.yml` and paste again in one go. There is no Postgres service in this
file and that is correct. `DATABASE_URL` is left unset, upstream then uses SQLite in the mounted
`database` directory, and that one file is the whole of your data.

## 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-kener
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Kener · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://kener.ing/docs/v4/setup/deployment 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. That same hostname is
# ORIGIN in .env: Kener hands ORIGIN to SvelteKit for the cross-site check on
# every form post, so if the two disagree the page loads and the sign-in fails.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		# The status page is public and the manage screens behind it are not,
		# and both share a hostname. SAMEORIGIN protects the second, at the cost
		# of the badge embeds Kener offers for other people's sites.
		X-Frame-Options "SAMEORIGIN"
		# Upstream reads the Origin header when the browser sends one and falls
		# back to SameSite=Lax cookies when it does not, so this costs nothing.
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8179 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:8179
}
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-kener /etc/caddy/Caddyfile`, reload,
and paste again. The commonest cause is a `<DOMAIN>` you replaced in the comment but left in
the site line. Caddy requests the certificate on the first request to the 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 `8179`, `6379` or `3000`.

If you do not: delete anything for `8179` with `sudo ufw delete allow 8179`. Compose binds it
to 127.0.0.1, so a rule for it would cover traffic that cannot arrive, and 6379 is never
published at all, so Redis has no host port a rule could apply to. Your checks need nothing
opened either: they are outbound requests from the container, and ufw governs what arrives.
`Status: inactive` is a different problem, because Prompt Zero left this firewall on, so
something has turned it off since; `sudo ufw enable` puts it back.

## 7. Start and verify

Kener runs its migrations and its seed on the way up, so the first boot writes the schema and a
starter status page before it answers anything. The loop below is why there is no fixed sleep.

```bash
cd /srv/kener
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>/healthcheck?strict=1'); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS https://<DOMAIN>/healthcheck; echo
curl -sSL https://<DOMAIN>/ | grep -c 'Service Status'
curl -sS -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/api/v1/monitors
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Create Admin Account'
```

You should see, in order: the loop reaching `200`, then
`{"status":"ok","db":true,"redis":true}`, then a number greater than `0` because
`Service Status` is the heading the seeded status page renders, then `401`, then another number
greater than `0`.

If you do not: the `?strict=1` on the loop is the part worth understanding. Upstream answers
`200` from `/healthcheck` even when the database or Redis is down, printing `"status":"degraded"`
in the body instead, and only the strict form turns a sick dependency into a `503`. So a bare
`200` proves nothing on its own; the body is the assert. The `401` is good news too: it means
the API refused a call carrying no bearer token. A `404` in place of the first three means Caddy
is reaching something other than Kener, so check `docker compose ps`. If the Kener container
never starts, run `docker compose logs --tail 20 redis` first, because a Redis that never
reports healthy holds the app back through `depends_on`, then
`docker compose logs --tail 40 kener`.

That last number is the one with a deadline on it. With no users in the database yet,
https://<DOMAIN>/account/signin is a `Create Admin Account` form, and it is open to whoever
loads the hostname first. Open it now, fill in a name, an email address and a password, and put
that password in your password manager. Then prove the window is shut:

```bash
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Create Admin Account'
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Sign In'
```

You should see: `0` from the first, and a number greater than `0` from the second.

If you do not: a `Create Admin Account` form that is still there means the account was not
created, not that the check is wrong. Upstream's signup action refuses once one user exists, so
there is no setting to switch and no second account to worry about. A running container was
never the finish line; these two numbers are.

## 8. First backup and restore

One archive: the SQLite database, the environment file, the compose file and the live Caddy
site block. Redis is not in it, because it holds queue and scheduler state that rebuilds
itself, while every monitor, incident, page, user and result is in the SQLite file.

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

You should see: one file, a few hundred kilobytes on a fresh install. The containers go down
for a few seconds on purpose, because a SQLite file copied mid-write is not a backup.

If you do not: an archive of about 100 bytes means `tar` found none of the paths, which happens
if a `-C` argument has a typo. Run `tar -tzf` on it and read what it actually contains; you
want `database/`, `.env`, `compose.yml` and `Caddyfile` in the listing.

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

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

You should see: one file copied, and it listed by `ls -lh ~/backups/kener/`.

If you do not: `Permission denied (publickey)` means you ran it on the server. The `vps:` prefix
only means something on your own machine, where the alias Prompt Zero created lives.

Now prove the restore, today, while the only thing at risk is an empty status page:

```bash
cd /srv/kener
docker compose down
sudo rm -rf /srv/kener/database
sudo install -d -m 750 -o 1000 -g 1000 /srv/kener/database
sudo tar -C /srv/kener -xzf /srv/kener/backups/kener-$(date +%F).tar.gz database .env compose.yml
docker compose up -d
sleep 30
curl -sSL https://<DOMAIN>/account/signin | grep -c 'Sign In'
```

You should see: a number greater than `0`, from a database directory that was deleted a minute
ago, which means your administrator account came back with it.

If you do not: `tar: database: Not found in archive` means the date in the filename does not
match, so run `ls /srv/kener/backups/` and use the real one. If the page offers to create an
admin account again, the restore put back an empty database and you are looking at a fresh
install. Know what the two halves are worth: `database/kener.sqlite.db` is your monitors, your
incident history and your account, and `.env` is the key that decrypts what Kener stored under
it. Neither is much use without the other.

## 9. Updating later

New versions are listed at https://github.com/rajnandan1/kener/releases. The release tag and
the image tag are the same string, so release `v4.1.3` is image tag `v4.1.3`. Take a backup
first, then edit the `image:` line in /srv/kener/compose.yml to the new tag and its digest.

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

You should see: migration output, then the server starting, and no repeating restart.

If you do not: put the old tag and digest back and run the same three commands. Kener runs its
migrations on the way up, so watch that log until it settles, then re-run step 7's health check
and the `Service Status` grep before you call the update done.

## 10. What will probably go wrong

The sign-in that fails on a page that loads. I had `ORIGIN` set with a trailing slash, and
everything else looked right: the status page rendered, the health check said ok, the
`Create Admin Account` form appeared. Submitting it returned a bare
`Cross-site POST form submissions are forbidden`, and I spent twenty minutes in Caddy's logs
looking for a problem that was one character in .env. Kener hands `ORIGIN` to SvelteKit, which
compares it against the host the browser used on every form post; a trailing slash, an `http://`
where the browser said `https://`, or a `www.` on one side only are all mismatches. If step 7's
account creation will not complete, run `grep ORIGIN /srv/kener/.env` first, fix it, then
`docker compose up -d --force-recreate` before touching anything else.

## 11. Out of scope

- Do not set `DATABASE_URL` and do not add a Postgres or MySQL service. SQLite is the choice
  here, and it is why the whole install is one directory and one file to copy.
- Do not configure SMTP, `RESEND_API_KEY`, or any alerting provider. Every one of them is an
  account or a key somewhere else, and you wire those up in the manage screens.
- Do not set `KENER_BASE_PATH` and do not switch to a `-status` image variant. Those exist for
  serving Kener under a subpath of a hostname that already has a site, and they are a different
  image built at a different base path.
- Do not publish 3000 or 6379 on the host and do not open either in the firewall. Caddy is the
  only way in, and Redis is reachable only from the other container.

325 lines · 14,997 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 Kener 4.1.2 and the Redis its scheduler needs under ~/selfhost/kener, answering at
http://localhost:8179.

## 1. Preflight

Say this to the user before step 2, because it decides whether they want this install at all.
A status page exists so other people can read it, and this one answers at
http://localhost:8179: this computer and nothing else, not a colleague, not their own phone.
Checks also run only while this machine is awake, and a closed laptop records nothing. What
they get is a private dashboard over their own sites.

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

`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. Kener plus Redis needs 1024 MB of RAM
available and 5 GB free on the home disk, and both images publish amd64 and arm64. On macOS and
Windows the memory figure is the host's, and Docker Desktop takes its allocation out of that.
If either floor is missed, print both numbers and stop. Do not install and hope.

## 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/kener/database ~/selfhost/kener/backups
ls -la ~/selfhost/kener
```

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

```bash
sudo chown -R 1000:1000 ~/selfhost/kener/database
```

Do not run that on macOS or Windows: Docker Desktop rewrites ownership across its file share,
so the container already sees itself as the owner. Assert: `ls -la` shows `database` and
`backups`, and on Linux `database` belongs to `1000`. Keep `database` on the local disk and
out of any synced folder: `kener.sqlite.db` needs real POSIX file locks.

## 4. Secrets

One secret, `KENER_SECRET_KEY`. Upstream documents it as the key that signs the session tokens
and encrypts stored credentials, and documents `openssl rand -base64 32` as the way to make
one. Git Bash ships openssl, so this runs the same on all three systems. Generate it here,
print it nowhere, and keep it out of your summary and any log.

`ORIGIN` is in the same file and is not a secret: it is what SvelteKit compares against on
every form post, http://localhost:8179, with no trailing slash.

```bash
umask 077
cat > ~/selfhost/kener/.env <<EOF
ORIGIN=http://localhost:8179
TZ=UTC
KENER_SECRET_KEY=$(openssl rand -base64 32)
EOF
chmod 600 ~/selfhost/kener/.env
umask 022
ls -l ~/selfhost/kener/.env
```

Assert: the file exists with mode `-rw-------`. Tell the user the key is in
~/selfhost/kener/.env, readable with `grep KENER_SECRET_KEY ~/selfhost/kener/.env`, and that
changing it signs everyone out and makes anything Kener encrypted under it unreadable, so it
belongs in their password manager today. On Windows those mode bits are advisory and the real
boundary is their own Windows account.

## 5. compose.yml

```bash
cat > ~/selfhost/kener/compose.yml <<'EOF'
# Kener · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   deployment ......... https://kener.ing/docs/v4/setup/deployment
#   environment ........ https://kener.ing/docs/v4/setup/environment-variables
#   database ........... https://kener.ing/docs/v4/setup/database-setup
#   image build ........ https://github.com/rajnandan1/kener/blob/v4.1.2/Dockerfile
#
# Two services, on the computer you are sitting at, every path relative to
# ~/selfhost/kener/ so one file works on macOS, Linux and Windows. Redis is not
# optional in v4: upstream calls it required for the queues, the cache and the
# scheduler, and its /data is a named volume because that image chowns its data
# directory to its own uid, which a Windows bind mount cannot allow. The
# database stays a bind mount and DATABASE_URL is unset, so upstream defaults
# to SQLite there, under the node user uid 1000, hence step 3's Linux-only
# chown. Digests read on 2026-08-07; both images publish amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  redis:
    image: redis:7.4.10-alpine@sha256:e7723ff73d963f5cc6d9c4643ea3d989527a402a319239054e9472a7fb9219a2
    container_name: kener-redis
    restart: unless-stopped
    volumes:
      # Queue state only: monitors and results are in the SQLite file below.
      - kener-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    # No `ports:` at all: 6379 is reachable only from the other container.

  kener:
    image: ghcr.io/rajnandan1/kener:v4.1.2@sha256:239ab635b900b3fe0a4e22f5599f77525211d1b7a25b8fcf3d173936ddacc1cc
    container_name: kener
    restart: unless-stopped
    env_file: ./.env
    environment:
      # Redis is on the compose network only, so this carries no credential.
      REDIS_URL: redis://redis:6379
      NODE_ENV: production
    volumes:
      # kener.sqlite.db: every monitor, incident, page, user and result.
      - ./database:/app/database
    ports:
      # Loopback only: no other device on the wifi can reach 8179.
      - "127.0.0.1:8179:3000"
    depends_on:
      redis:
        condition: service_healthy

volumes:
  kener-redis-data:
EOF
cd ~/selfhost/kener && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. Two services, one published port.

## 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, and browsers
treat http://localhost as a secure context anyway. Nothing is published past loopback, so no
port needs closing.

8179 is bound to 127.0.0.1: not the user's phone, not a laptop on the same wifi, nobody on the
internet. For most apps that is a fair trade; for a status page it is the trade, because being
readable by somebody else is what this software exists to do. Confirm the binding:

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

Assert: that prints `1`, the one published-port line `- "127.0.0.1:8179:3000"`. Redis publishes
no host port. The checks still reach the internet: loopback governs what arrives, not what a
container can call.

## 7. Start and verify

Kener runs migrations and a seed on the way up, so the first boot writes a schema and a starter
page before answering. Use the loop, not a fixed sleep.

```bash
cd ~/selfhost/kener
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:8179/healthcheck?strict=1'); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS http://localhost:8179/healthcheck; echo
curl -sSL http://localhost:8179/ | grep -c 'Service Status'
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8179/api/v1/monitors
curl -sSL http://localhost:8179/account/signin | grep -c 'Create Admin Account'
```

Assert all five, and print what you received for each. The loop ends on `200`, and it asks
with `?strict=1` on purpose: upstream answers `200` from `/healthcheck` even when a dependency
is down, and only the strict form turns that into `503`. The plain call then prints
`{"status":"ok","db":true,"redis":true}`, and all three fields matter. The third prints a
number greater than `0`, because `Service Status` is the heading the seeded page renders. The
API call prints `401`, upstream's answer to a request with no bearer token. The last prints a
number greater than `0`, because with no users yet the sign-in page is a `Create Admin Account`
form. If any of the five misses, stop, run `docker compose logs --tail 40 kener`, then
`docker compose logs --tail 20 redis`: a Redis that never reports healthy holds the app in
`depends_on`. If `port is already allocated` came back, find what holds 8179
(`lsof -nP -iTCP:8179 -sTCP:LISTEN`, `ss -ltnp | grep 8179` on Linux,
`netstat -ano | findstr :8179` on Windows) and stop until the user frees it: 8179 is inside
`ORIGIN`. A running container is not success.

STOP: tell the user to open http://localhost:8179/account/signin, fill in a name, an email
address and a password to create the administrator account, and save that password in their
password manager. Do not continue until they confirm.

Once they confirm, prove the setup form is gone:

```bash
curl -sSL http://localhost:8179/account/signin | grep -c 'Create Admin Account'
curl -sSL http://localhost:8179/account/signin | grep -c 'Sign In'
```

Assert: the first prints `0`, the second a number greater than `0`. Upstream's signup action
refuses once a user exists, so that page is a login form from here on.

## 8. First backup and restore

One archive: the SQLite database, the environment file and the compose file. Redis is not in
it, because it holds only queue state that rebuilds itself.

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

Assert: the archive exists and is non-empty. Print its size. The containers stop for a few
seconds on purpose, because a SQLite file copied mid-write is not a backup.

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

To restore: `cd ~/selfhost/kener`, `docker compose down`, `rm -rf database`, untar the archive
there, then `docker compose up -d`. `database/kener.sqlite.db` is their monitors, their
incidents and their account; `.env` is the key that decrypts what Kener stored under it.

## 9. Updating later

New versions are at https://github.com/rajnandan1/kener/releases, and the release tag is the
image tag. Take a backup first, then edit the image line in ~/selfhost/kener/compose.yml to the
new tag and its digest:

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

Kener migrates on the way up, so watch that log until it settles, then re-run step 7's health
check and the `Service Status` grep before calling the update done.

## 10. What will probably go wrong

I rebooted, opened http://localhost:8179 out of habit, and got a connection error that read
like a lost database. It was not. Docker Desktop had not started with the session, so nothing
was listening on 8179 and no check had run since the reboot: `restart: unless-stopped` acts
only once the Docker daemon is up. Turn on its start-at-login setting, and after a reboot run
`cd ~/selfhost/kener && docker compose up -d` before concluding anything broke. The quieter
version: uptime is worked out from the results that exist, so hours when this machine slept
leave no failed result and read as clean.

## 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 8179 to 0.0.0.0 and do not point `ORIGIN` at this machine's LAN address. That
  publishes a page listing every URL the user monitors, plus its sign-in form, on every network
  this machine joins.
- Do not set `DATABASE_URL` and do not add a Postgres or MySQL service. SQLite is why this is
  one folder to copy.
- Do not configure SMTP, `RESEND_API_KEY`, or any alerting provider. Each is an account or key
  somewhere else.

# Kener · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   deployment ......... https://kener.ing/docs/v4/setup/deployment
#   environment ........ https://kener.ing/docs/v4/setup/environment-variables
#   database ........... https://kener.ing/docs/v4/setup/database-setup
#   image build ........ https://github.com/rajnandan1/kener/blob/v4.1.2/Dockerfile
#
# Two services, on the computer you are sitting at, every path relative to
# ~/selfhost/kener/ so one file works on macOS, Linux and Windows. Redis is not
# optional in v4: upstream calls it required for the queues, the cache and the
# scheduler, and its /data is a named volume because that image chowns its data
# directory to its own uid, which a Windows bind mount cannot allow. The
# database stays a bind mount and DATABASE_URL is unset, so upstream defaults
# to SQLite there, under the node user uid 1000, hence step 3's Linux-only
# chown. Digests read on 2026-08-07; both images publish amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  redis:
    image: redis:7.4.10-alpine@sha256:e7723ff73d963f5cc6d9c4643ea3d989527a402a319239054e9472a7fb9219a2
    container_name: kener-redis
    restart: unless-stopped
    volumes:
      # Queue state only: monitors and results are in the SQLite file below.
      - kener-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    # No `ports:` at all: 6379 is reachable only from the other container.

  kener:
    image: ghcr.io/rajnandan1/kener:v4.1.2@sha256:239ab635b900b3fe0a4e22f5599f77525211d1b7a25b8fcf3d173936ddacc1cc
    container_name: kener
    restart: unless-stopped
    env_file: ./.env
    environment:
      # Redis is on the compose network only, so this carries no credential.
      REDIS_URL: redis://redis:6379
      NODE_ENV: production
    volumes:
      # kener.sqlite.db: every monitor, incident, page, user and result.
      - ./database:/app/database
    ports:
      # Loopback only: no other device on the wifi can reach 8179.
      - "127.0.0.1:8179:3000"
    depends_on:
      redis:
        condition: service_healthy

volumes:
  kener-redis-data: