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

Ubuntu's `ttyd` package starts its own `ttyd.service`, which runs **`login` on port 7681** -- our
port. Left running, it takes the port, and Apache hands visitors the server's own login prompt
(found 2026-11-08, after step 5). Disable it first:

```bash
systemctl disable --now ttyd                 # the package's service: a login prompt on 7681
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
ss -ltnp | grep 7681                          # the ttyd of starshipos-demo, nothing else
```

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. The check (done 2026-11-08)

From outside: a session ready 1.5 s after the page opens; `3 4 + .` answers `7  ok`, `: SQUARE DUP *
;  7 SQUARE .` answers `49  ok`; a third visitor at once is told every machine is busy. The
certificate is try.starshipos-f18.com's own (Let's Encrypt), and only the .com may frame it.

## 7. 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` -- a session's QEMU holds ~150 MB of its 384 MiB guest; two at most
  (`DEMO_MAX_GUESTS` in the service)
- CPU: an idle guest keeps a host core busy (the kernel's idle loop polls -- its own issue), so the
  service caps all sessions together at one core (`CPUQuota=100%`, `Nice=19`). After changing the
  service file: `systemctl daemon-reload && systemctl restart starshipos-demo`