demo: DEPLOY.md, the server checklist for Try it [skip ci]

Five steps on the server after #148: the checkout and amd64 build tools,
the demo's own Zuse, the image and the saved machine at 384 MiB, the
service, TLS and Apache for try.starshipos-f18.com; then the check from
outside and the .com's navigation link (#115, #116, #117).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2

demo/DEPLOY.md

@@ -0,0 +1,80 @@
+# Deploying "Try it" on the server
+
+The public demo: each visitor gets a StarshipOS machine of their own in the browser, resumed at
+Zuse's prompt, gone when they leave. Two at a time on today's server (384 MiB each); a third visitor
+is told every machine is busy and to try back in a few minutes. Issues #115, #116, #117.
+
+Run as root on the server, **after PR #148 is merged** (it carries the 384 MiB guests and the busy
+message), **while CI is idle** (each step that boots QEMU boots one, in the foreground).
+
+## 1. The checkout and what the build needs (~15 min)
+
+```bash
+apt-get install -y ttyd qemu-system-x86 ovmf python3 git
+git clone https://gitea.starshipos-f18.org/rajames/LithosAnanke.git /opt/starshipos-demo
+cd /opt/starshipos-demo
+git checkout master                  # after #148: alpha.3's kernel, and the demo's limits
+make ARCH=amd64 init INIT_DOCS=0 INIT_PROOFS=0     # amd64 only: no docs, no Isabelle
+```
+
+Master after #148 is the `v4.0.0-alpha.3` kernel unchanged, plus #148's scripts.
+
+## 2. The demo's own Zuse (~3 min, two QEMU boots)
+
+```bash
+demo/mint-zuse.sh /var/lib/starshipos-demo-zuse
+ls -la /var/lib/starshipos-demo-zuse/zusestick.img     # the stick every session attaches
+```
+
+Never anyone's real Zuse: minted for the demo (#111), its writes discarded in every session.
+
+## 3. The image and the saved machine (~2 min, one QEMU boot)
+
+```bash
+demo/build-iso.sh /tmp/StarshipOS.iso
+DEMO_PROMPT='[zuse@Hera]' demo/make-snapshot.sh /tmp/StarshipOS.iso /var/lib/starshipos-demo \
+    /var/lib/starshipos-demo-zuse/zusestick.img
+ls -la /var/lib/starshipos-demo/            # StarshipOS.iso identity.img vars.fd state
+```
+
+The saved machine belongs to this image, this QEMU and 384 MiB: re-run step 3 after any of them
+changes. Sessions already running keep theirs.
+
+## 4. The service (~5 min)
+
+```bash
+useradd --system --home /var/lib/starshipos-demo --shell /usr/sbin/nologin starshipos-demo
+chown -R starshipos-demo: /var/lib/starshipos-demo
+cp demo/starshipos-demo.service /etc/systemd/system/
+systemctl daemon-reload && systemctl enable --now starshipos-demo
+systemctl status starshipos-demo --no-pager | head -5
+curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:7681/     # 200: ttyd answers
+```
+
+The service expects the checkout's `demo/` at `/opt/starshipos-demo/demo` (step 1 put it there).
+
+## 5. TLS and Apache for try.starshipos-f18.com (~10 min)
+
+DNS: `try.starshipos-f18.com` must point at this server (an A record) before certbot.
+
+```bash
+a2enmod proxy proxy_http proxy_wstunnel headers ssl rewrite
+certbot certonly --apache -d try.starshipos-f18.com
+cp demo/apache-demo.conf /etc/apache2/sites-available/starshipos-demo.conf
+a2ensite starshipos-demo && apachectl configtest && systemctl reload apache2
+curl -sI https://try.starshipos-f18.com/ | head -3                   # 200, its own certificate
+```
+
+`apache-demo.conf` lets only the .com frame the terminal (`frame-ancestors`).
+
+## 6. Tell Claude
+
+Then I check from outside: a session reaches `[zuse@Hera] ok>`, `3 4 + .` answers `7 ok`, a third
+visitor gets the busy message, and the .com's Try it page shows the console. Then the "Try it" link
+goes into the .com's navigation (#117).
+
+## If something goes wrong
+
+- `journalctl -u starshipos-demo -n 50` -- ttyd and the sessions
+- A session that ends at once: the saved machine does not match (re-run step 3)
+- Memory: `free -h` -- each session is ~400 MB of QEMU; two at most (`DEMO_MAX_GUESTS` in the service)

demo/README.md

@@ -20,7 +20,8 @@ XWiki "Try it" page (iframe) -> Apache: TLS, websocket -> ttyd -> start-session.
 | `start-session.sh` | One visitor's session: resumes the saved machine, ends it on hang-up, close or time-out (#112) |
 | `console.py` | Joins the visitor's terminal to the machine only once it runs, discarding keys typed while it loads |
 | `qemu-args.sh` | The machine, shared by the two above: a resumed machine must match the saved one exactly |
-| `starshipos-demo.service` | ttyd as a systemd service, on localhost, at most 3 sessions (#114) |
+| `starshipos-demo.service` | ttyd as a systemd service, on localhost; two guests at once, a busy message for the rest (#114, #116) |
+| `DEPLOY.md` | Putting it on the server, step by step |
 | `apache-demo.conf` | Example vhost: TLS, the websocket, framing allowed for the `.com` only (#115) |
 | `xwiki-try-it.xwiki` | The "Try it" page, its own page on the `.com` XWiki (`TryIt`), in the landing page's style |