From 0dbad0f2780cb836b787e4e2c83f3263670c2c85 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Nov 2026 00:07:58 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2 --- demo/DEPLOY.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++ demo/README.md | 3 +- 2 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 demo/DEPLOY.md diff --git a/demo/DEPLOY.md b/demo/DEPLOY.md new file mode 100644 index 00000000..fbc8b438 --- /dev/null +++ b/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) diff --git a/demo/README.md b/demo/README.md index 02df67a1..484d039f 100644 --- a/demo/README.md +++ b/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 |