site serve and view: the by-hand checks that need a spare VM and a browser #243

New issue

Open

opened 2026-09-28 16:13:07 +01:00 by allod-agent · 0 comments

allod-agent commented

2026-09-28 16:13:07 +01:00

Member

Finish the by-hand checks of allod site serve and allod site view that need a spare VM and a browser, so that every row of the documentation's table is something seen and not something expected.

Primary goals:

Reload reaches a real browser — an edit in the VM changes the page on the hypervisor without a refresh.
The forward ends when the VM does — view returns by itself when the VM shuts down or the link drops, and how long that takes is written down.
What a preview does when nobody is logged in — measured, and the sentence in the documentation that says "not measured" replaced by the result.
The registry path with a real site — view without --vm and without --port, finding both from the inventory.

What is already seen

The commands landed in allod/tools#242 for allod/tools#240. In the VM, against real Nix and systemd: tests/site-preview-by-hand.sh passes 9 of 9, and the zola, plain HTML and Vite examples each serve, are found again, and stop.

From the hypervisor, run by the owner against a stand-in site served in allod-dev under the id allod/tools:

Command	Seen
`allod site view --vm allod-dev --port 18520 allod/tools`	printed `http://127.0.0.1:18520` and held the terminal until Ctrl-C
`ss -ltn \| grep 18520`, after Ctrl-C	nothing: the port on the hypervisor was free
`ssh -- allod-dev systemctl --user is-active allod-preview-allod-tools`, after Ctrl-C	`active`: the server kept running
`allod site serve --stop --vm allod-dev allod/tools`	no output, exit 0
the same again	`allod-preview-allod-tools is not running`

Earlier, also from the hypervisor: systemctl --user works in a non-interactive ssh <vm> <command>, and allod is on the path of such a command.

What is left

Each is one observation. A result that contradicts docs/allod-site-preview.md changes the document, or becomes a bug report of its own.

Check	How	Expected
The page shows in a browser through the forward	`allod site view <site>`, open the printed address	the site's page
Reload without a refresh	with the page open, change a source file of the site in the VM	the browser shows the change by itself. So far only a WebSocket client has been seen to receive the reload message
A refusal crosses SSH readably	`allod site view --vm <vm> --port <n> <id>` for a repository whose flake has no `preview` app and no preview running	the message names `apps.<system>.preview`; `view` exits 1 and forwards nothing
`view` finds the VM and the port itself	for a site whose registry entry has a `preview_port` and which one machine in `vm-specs.json` lists: `allod site view <site>`	the same as with `--vm` and `--port`
The VM shuts down	with `view` running, shut the VM down	`view` returns by itself; note after how many seconds
The link drops silently	with `view` running, cut the VM's network without shutting it down	`view` returns within about 15 seconds (`ServerAliveInterval=5`, `ServerAliveCountMax=3`); the server is unaffected
`ssh` is killed outright	`kill -9` the `ssh` that `view` became	the port on the hypervisor is free
The server crashes	kill the server's process in the VM while `view` runs	the forward stays up, the browser shows a connection error, `allod site serve` starts it again
The last login session ends	with nobody logged in to the VM: `ssh -- <vm> systemd-run --user --collect --quiet --unit allod-preview-q2 -- sleep 600`, wait a minute, `ssh -- <vm> systemctl --user is-active allod-preview-q2`	unknown. `active` means a preview started from the hypervisor survives; `inactive` means it goes with the session, and the help text says so. Lingering is not turned on to hide it

A stand-in is enough for every row but the fourth: any directory in the VM that is a git repository with a site.toml and the plain HTML flake from docs/allod-site-preview.md, served with allod site serve --port <n> from inside it.

Scope

In scope: running the checks above, correcting docs/allod-site-preview.md and the help text where a result differs, and replacing the "not measured" sentence.

Not in scope: a change to how either command behaves. A check that fails is reported as a bug and fixed under its own issue.

Trigger: a VM is free to be shut down and logged out of. With two dev VMs in use and a third not fitting on the hypervisor, that is when one of the two is idle.

Finish the by-hand checks of `allod site serve` and `allod site view` that need a spare VM and a browser, so that every row of the documentation's table is something seen and not something expected. Primary goals: - **Reload reaches a real browser** — an edit in the VM changes the page on the hypervisor without a refresh. - **The forward ends when the VM does** — `view` returns by itself when the VM shuts down or the link drops, and how long that takes is written down. - **What a preview does when nobody is logged in** — measured, and the sentence in the documentation that says "not measured" replaced by the result. - **The registry path with a real site** — `view` without `--vm` and without `--port`, finding both from the inventory. ### What is already seen The commands landed in allod/tools#242 for allod/tools#240. In the VM, against real Nix and systemd: `tests/site-preview-by-hand.sh` passes 9 of 9, and the zola, plain HTML and Vite examples each serve, are found again, and stop. From the hypervisor, run by the owner against a stand-in site served in `allod-dev` under the id `allod/tools`: | Command | Seen | | --- | --- | | `allod site view --vm allod-dev --port 18520 allod/tools` | printed `http://127.0.0.1:18520` and held the terminal until Ctrl-C | | `ss -ltn \| grep 18520`, after Ctrl-C | nothing: the port on the hypervisor was free | | `ssh -- allod-dev systemctl --user is-active allod-preview-allod-tools`, after Ctrl-C | `active`: the server kept running | | `allod site serve --stop --vm allod-dev allod/tools` | no output, exit 0 | | the same again | `allod-preview-allod-tools is not running` | Earlier, also from the hypervisor: `systemctl --user` works in a non-interactive `ssh <vm> <command>`, and `allod` is on the path of such a command. ### What is left Each is one observation. A result that contradicts `docs/allod-site-preview.md` changes the document, or becomes a bug report of its own. | Check | How | Expected | | --- | --- | --- | | The page shows in a browser through the forward | `allod site view <site>`, open the printed address | the site's page | | Reload without a refresh | with the page open, change a source file of the site in the VM | the browser shows the change by itself. So far only a WebSocket client has been seen to receive the reload message | | A refusal crosses SSH readably | `allod site view --vm <vm> --port <n> <id>` for a repository whose flake has no `preview` app and no preview running | the message names `apps.<system>.preview`; `view` exits 1 and forwards nothing | | `view` finds the VM and the port itself | for a site whose registry entry has a `preview_port` and which one machine in `vm-specs.json` lists: `allod site view <site>` | the same as with `--vm` and `--port` | | The VM shuts down | with `view` running, shut the VM down | `view` returns by itself; note after how many seconds | | The link drops silently | with `view` running, cut the VM's network without shutting it down | `view` returns within about 15 seconds (`ServerAliveInterval=5`, `ServerAliveCountMax=3`); the server is unaffected | | `ssh` is killed outright | `kill -9` the `ssh` that `view` became | the port on the hypervisor is free | | The server crashes | kill the server's process in the VM while `view` runs | the forward stays up, the browser shows a connection error, `allod site serve` starts it again | | The last login session ends | with nobody logged in to the VM: `ssh -- <vm> systemd-run --user --collect --quiet --unit allod-preview-q2 -- sleep 600`, wait a minute, `ssh -- <vm> systemctl --user is-active allod-preview-q2` | unknown. `active` means a preview started from the hypervisor survives; `inactive` means it goes with the session, and the help text says so. Lingering is not turned on to hide it | A stand-in is enough for every row but the fourth: any directory in the VM that is a git repository with a `site.toml` and the plain HTML flake from `docs/allod-site-preview.md`, served with `allod site serve --port <n>` from inside it. ### Scope In scope: running the checks above, correcting `docs/allod-site-preview.md` and the help text where a result differs, and replacing the "not measured" sentence. Not in scope: a change to how either command behaves. A check that fails is reported as a bug and fixed under its own issue. Trigger: a VM is free to be shut down and logged out of. With two dev VMs in use and a third not fitting on the hypervisor, that is when one of the two is idle.