docs: add terminal screencast

Signed-off-by: Paul Meyer <[email protected]>

docs/screencast/README.md

@@ -0,0 +1,42 @@
+# Screencast / Asciinema
+
+[Asciinema](https://github.com/asciinema/asciinema) is used to automatically generate
+terminal session recordings for our documentation. To fully automate this we use scripts
+that utilize [expect](https://manpages.debian.org/testing/expect/expect.1.en.html) to interface with different
+CLI tools, and run them inside a [container](docker/Dockerfile).
+
+## Usage
+
+```sh
+./generate-screencasts.sh
+```
+
+This will:
+
++ build the container
++ run the expect based scripts
++ copy recordings into the recordings directory
+
+To replay the output you can use `asciinema play recordings/verify-cli.cast`.
+
+Include the generated screencast into our docs using the [`AsciinemaWidget`](../src/components/AsciinemaWidget/index.js):
+
+```md
+import AsciinemaWidget from '../../src/components/AsciinemaWidget';
+
+<AsciinemaWidget src="/constellation/assets/verify-cli.cast" fontSize={16} rows={20} cols={112} idleTimeLimit={3} preload={true} theme={'edgeless'} />
+```
+
+Then [re-build and locally host the docs](../README.md).
+
+## Styling
+
+There are three different locations were styling is applied:
+
+1. **The prompt** is styled using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
+More explanation and the actual color codes can be found in [Dockerfile](docker/Dockerfile).
+2. **Player dimensions** are passed to the [`AsciinemaWidget`](../src/components/AsciinemaWidget/index.js)
+when it's [embedded in the docs](../docs/workflows/verify-cli.md). Check the `asciinema-player` for a
+[full list of options](https://github.com/asciinema/asciinema-player#options).
+3. **Everything else** is [styled via CSS](../src/css/custom.css). This includes the option to build a custom
+[player theme](https://github.com/asciinema/asciinema-player/wiki/Custom-terminal-themes).

docs/screencast/docker/Dockerfile

@@ -0,0 +1,30 @@
+FROM ubuntu:22.04@sha256:2b7412e6465c3c7fc5bb21d3e6f1917c167358449fecac8176c6e496e5c1f05f
+
+# Install requirements
+RUN apt-get update && apt-get install -y software-properties-common &&\
+    apt-add-repository ppa:zanchey/asciinema && apt-get update &&\
+    apt-get install -y curl jq expect asciinema sudo unzip &&\
+    rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSLO https://dl.k8s.io/release/v1.26.0/bin/linux/amd64/kubectl &&\
+    sudo install kubectl /usr/local/bin/kubectl && rm kubectl
+
+# As mount point for $HOME/.kube/config
+RUN mkdir /root/.kube
+
+# Enable RGB colors in PS1
+ENV TERM=xterm-256color
+# Set width of terminal, default is ~80 and leads to broken lines for long lines,
+# e.g., curl & cosign commands.
+ENV COLUMNS=512
+# For PS1 to work shell needs to specified
+ENV SHELL=/bin/bash
+# ANSI color codes are used to control PS1 prompt. We use "\033[38;2;<r>;<g>;<b>m"
+# to control the foreground color with RBG colors [1]. Non-printable characters
+# need to  be escaped with additional \[ and \], see [2].
+# [1]: https://stackoverflow.com/a/33206814/2306355
+# [2]: https://stackoverflow.com/a/19501528/2306355
+RUN echo 'export PS1="\[\033[38;2;139;4;221m\]$\[\033[0m\] "' >> /root/.bashrc
+
+WORKDIR /demo
+ENTRYPOINT ["/usr/bin/expect", "-f"]

docs/screencast/generate-screencasts.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+#
+# This script prepares the environment for expect scripts to be recorded in,
+# executes all scripts, and copies the .cast files to our doc's asset folder.
+#
+
+set -euo pipefail
+
+# Setup.
+
+demodir=$(just demodir)
+docker build -t screenrecodings docker
+
+# Screencast.
+docker run -it \
+  -v "${HOME}/.kube/config:/root/.kube/config" \
+  -v "$(pwd)/recordings:/recordings" \
+  -v "${demodir}:/demo" \
+  -v "${demodir}/contrast:/usr/local/bin/contrast" \
+  -v "$(pwd)/scripts:/scripts" \
+  screenrecodings /scripts/flow.expect
+
+# Cleanup.
+kubectl delete -f "${demodir}/deployment/"
+kubectl delete -f "${demodir}/coordinator.yaml"