LithosAnanke/demo/DEPLOY.md

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)

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)

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)

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)

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.

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)