Figure out and document styling of player.

Signed-off-by: Fabian Kammel <fk@edgeless.systems>
This commit is contained in:
Fabian Kammel 2023-02-13 12:26:50 +00:00 committed by Moritz Eckert
parent ad103e6d7a
commit 2f5bb77fbb
12 changed files with 2860 additions and 1114 deletions

View file

@ -0,0 +1,61 @@
# 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://linux.die.net/man/1/expect) 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 assets folder of our docs
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={18} cols={80} 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. **Font size and player dimensions** are passed to the [`AsciinemaWidget`](../src/components/AsciinemaWidget/index.js)
when it is [embedded in the docs](../docs/workflows/verify-cli.md#5). 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).
## GitHub README.md
The GitHub `README.md` does not support embedding the `asciinema-player`, therefore we generate an
`svg` file for that usecase.
{"version": 2, "width": 0, "height": 0, "timestamp": 1676289328, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}}
=> TODO: Automate that change
{"version": 2, "width": 95, "height": 17, "timestamp": 1676289328, "env": {"SHELL": "/bin/bash", "TERM": "xterm-256color"}}
```sh
# https://github.com/nbedos/termtosvg
# Archived since 2020, do we want to change?
pip3 install termtosvg
# Window-frame.svg contains the styling information
termtosvg render recordings/readme.cast readme.svg -t window-frame.svg
cp readme.svg ../static/img/shell-windowframe.svg
```

66
docs/screencasts/demo.svg Normal file
View file

@ -0,0 +1,66 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" id="terminal" baseProfile="full" viewBox="0 0 143 285" width="143" version="1.1">
<defs>
<termtosvg:template_settings xmlns:termtosvg="https://github.com/nbedos/termtosvg">
<termtosvg:screen_geometry columns="12" rows="12"/>
<termtosvg:animation type="css"/>
</termtosvg:template_settings>
<style type="text/css" id="generated-style"><![CDATA[#screen {
font-family: 'DejaVu Sans Mono', monospace;
font-style: normal;
font-size: 14px;
}
text {
dominant-baseline: text-before-edge;
white-space: pre;
}
:root {
--animation-duration: 1001ms;
}
@keyframes roll {
0.000%{transform:translateY(0px)}
0.100%{transform:translateY(-238px)}
100.000%{transform:translateY(-238px)}
}
#screen_view {
animation-duration: 1001ms;
animation-iteration-count:infinite;
animation-name:roll;
animation-timing-function: steps(1,end);
animation-fill-mode: forwards;
}
]]></style>
<style type="text/css" id="user-style">
/* The colors defined below are the default 16 colors used for rendering text of the terminal. Adjust
them as needed.
gjm8 color theme (source: https://terminal.sexy/) */
/* customized colors 10, 11, and 14 */
.foreground {fill: #f8f8f2}
.background {fill: #272822}
.color0 {fill: #272822}
.color1 {fill: #f92672}
.color2 {fill: #a6e22e}
.color3 {fill: #f4bf75}
.color4 {fill: #66d9ef}
.color5 {fill: #ae81ff}
.color6 {fill: #a1efe4}
.color7 {fill: #f8f8f2}
.color8 {fill: #75715e}
.color9 {fill: #fd971f}
.color10 {fill: #8b04dd}
.color11 {fill: #dcaf3b}
.color12 {fill: #a59f85}
.color13 {fill: #f5f4f1}
.color14 {fill: #90ff99}
.color15 {fill: #f9f8f5}
</style>
</defs>
<rect id="terminalui" class="background" width="100%" height="100%" ry="4.5826941"/>
<circle cx="24" cy="23" r="7" class="color1"/>
<circle cx="44" cy="23" r="7" class="color3"/>
<circle cx="64" cy="23" r="7" class="color2"/>
<svg id="screen" width="96" height="204" x="23" y="50" viewBox="0 0 96 204" preserveAspectRatio="xMidYMin slice"><rect class="background" height="100%" width="100%" x="0" y="0"/><defs><g id="g1"><text x="0" textLength="8" class="background"> </text></g><g id="g2"><text x="0" textLength="96" class="foreground">\[\e[43;30m\</text></g><g id="g3"><text x="0" textLength="96" class="foreground">][\t]\w\r\n[</text></g><g id="g4"><text x="0" textLength="96" class="foreground">\u@\h]\$\[\e</text></g><g id="g5"><text x="0" textLength="40" class="foreground">[0m\]</text><text x="40" textLength="8" class="background"> </text></g></defs><g id="screen_view"><g><rect x="0" y="0" width="8" height="17" class="foreground"/><use xlink:href="#g1" y="0"/></g><g><use xlink:href="#g2" y="238"/><use xlink:href="#g3" y="255"/><use xlink:href="#g4" y="272"/><rect x="40" y="289" width="8" height="17" class="foreground"/><use xlink:href="#g5" y="289"/></g></g></svg>
</svg>

After

Width:  |  Height:  |  Size: 3.4 KiB

View file

@ -14,9 +14,18 @@ ENV PATH="${PATH}:/usr/local/go/bin:/root/go/bin"
RUN go install github.com/sigstore/cosign/cmd/cosign@latest
RUN go install github.com/sigstore/rekor/cmd/rekor-cli@latest
ENV SHELL=/bin/bash
# Enable RGB colors in PS1
ENV TERM=xterm-256color
ENV COLUMNS=200
# 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;144;255;153m\]~/constellation\[\033[0m\]\r\n\[\033[38;2;139;4;221m\]$\[\033[0m\] "' >> /root/.bashrc
# Copy install scripts

View file

@ -7,7 +7,7 @@ set CTRLC \003
set record_name [lindex $argv 0];
proc expect_prompt {} {
# make sure this matches your prompt
# This matches the trailing 0m of our ANSI control sequence. See PS1 in Dockerfile.
expect "0m "
}
@ -17,12 +17,6 @@ proc run_command {cmd} {
expect -timeout 1
}
proc send_keystroke_to_interactive_process {key {addl_sleep 2}} {
send "$key"
expect -timeout 1
sleep $addl_sleep
}
# Start recording
spawn asciinema rec --overwrite /recordings/check-sbom.cast
send "\r"
@ -47,7 +41,7 @@ run_command "curl -sLO https://github.com/edgelesssys/constellation/releases/lat
expect_prompt
run_command "grype constellation.spdx.sbom -o table -q"
expect_prompt
run_command "echo We are safe! :)"
run_command "echo We are safe!"
# Stop recording
send "exit"

View file

@ -2,18 +2,19 @@
# Note: Expects to be able to run 'sudo install' without a password
set timeout -1
set send_human {0.005 0.015 1 0.05 0.3}
set send_human {0.05 0 1 0.05 0.3}
set CTRLC \003
set record_name [lindex $argv 0];
proc expect_prompt {} {
# make sure this matches your prompt
# This matches the trailing 0m of our ANSI control sequence. See PS1 in Dockerfile.
expect "0m "
}
proc run_command {cmd} {
send -h "$cmd\r"
expect -timeout 3
send -h "$cmd"
send "\r"
expect -timeout 1
}
# Start recording
@ -22,25 +23,26 @@ send "\r"
expect_prompt
### Step 0: Requirements
# run_command "echo Step 0: Installing requirements"
# expect_prompt
# run_command "go install github.com/sigstore/cosign/cmd/cosign@latest"
# expect_prompt
# run_command "go install github.com/sigstore/rekor/cmd/rekor-cli@latest"
# expect_prompt
run_command "echo Step 0: Installing requirements"
expect_prompt
run_command "go install github.com/sigstore/cosign/cmd/cosign@latest"
expect_prompt
run_command "go install github.com/sigstore/rekor/cmd/rekor-cli@latest"
expect_prompt
### Step 1: Download CLI
run_command "echo Step 1: Download CLI and signature"
expect_prompt
run_command "curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64"
run_command "curl -sLO https://github.com/edgelesssys/constellation/releases/download/v2.2.2/constellation-linux-amd64"
expect_prompt
run_command "curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64.sig"
run_command "curl -sLO https://github.com/edgelesssys/constellation/releases/download/v2.2.2/constellation-linux-amd64.sig"
expect_prompt
### Step 2: Verify the CLI using cosign
run_command "echo Step 2: Verify the CLI using cosign and the public Rekor transparency log"
expect_prompt
run_command "COSIGN_EXPERIMENTAL=1 cosign verify-blob --key https://edgeless.systems/es.pub --signature constellation-linux-amd64.sig constellation-linux-amd64"
# run_command "COSIGN_EXPERIMENTAL=1 cosign verify-blob --key https://edgeless.systems/es.pub --signature constellation-linux-amd64.sig constellation-linux-amd64"
run_command "COSIGN_EXPERIMENTAL=1 cosign verify-blob --key https://github.com/edgelesssys/constellation/releases/download/v2.2.2/cosign.pub --signature constellation-linux-amd64.sig constellation-linux-amd64"
expect_prompt
### Step 2b: Verify the CLI manually

View file

@ -3,14 +3,9 @@
docker build -t screenrecodings docker
# Generate cast to verify CLI
docker run -it -v "$(pwd)"/recordings:/recordings screenrecodings
docker run -it -v "$(pwd)"/recordings:/recordings screenrecodings verify-cli.sh
cp recordings/verify-cli.cast ../static/assets/verify-cli.cast
# Generate cast to check SBOM
# docker run -it -v "$(pwd)"/recordings:/recordings screenrecodings check-sbom.sh /recordings/check-sbom.cast
# cp recordings/check-sbom.cast ../static/assets/check-sbom.cast
# docker rm -f recorder || true
# docker build -t screenrecodings docker
# docker run --name recorder -d -v "$(pwd)"/recordings:/recordings screenrecodings
# docker exec recorder /bin/bash < . check-sbom.sh /recordings/check-sbom.cast
docker run -it -v "$(pwd)"/recordings:/recordings screenrecodings check-sbom.sh
cp recordings/check-sbom.cast ../static/assets/check-sbom.cast

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 817 KiB

View file

@ -0,0 +1,38 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" id="terminal" baseProfile="full" viewBox="0 0 703 404" width="703" version="1.1">
<defs>
<termtosvg:template_settings xmlns:termtosvg="https://github.com/nbedos/termtosvg">
<termtosvg:screen_geometry columns="82" rows="19"/>
<termtosvg:animation type="css"/>
</termtosvg:template_settings>
<style type="text/css" id="generated-style"></style>
<style type="text/css" id="user-style">
/* The colors defined below are the default 16 colors used for rendering text of the terminal. Adjust
them as needed.
gjm8 color theme (source: https://terminal.sexy/) */
/* customized colors 10, 11, and 14 */
.foreground {fill: #f8f8f2}
.background {fill: #272822}
.color0 {fill: #272822}
.color1 {fill: #f92672}
.color2 {fill: #a6e22e}
.color3 {fill: #f4bf75}
.color4 {fill: #66d9ef}
.color5 {fill: #ae81ff}
.color6 {fill: #a1efe4}
.color7 {fill: #f8f8f2}
.color8 {fill: #75715e}
.color9 {fill: #fd971f}
.color10 {fill: #8b04dd}
.color11 {fill: #dcaf3b}
.color12 {fill: #a59f85}
.color13 {fill: #f5f4f1}
.color14 {fill: #90ff99}
.color15 {fill: #f9f8f5}
</style>
</defs>
<rect id="terminalui" class="background" width="100%" height="100%" ry="4.5826941"/>
<circle cx="24" cy="23" r="7" class="color1"/>
<circle cx="44" cy="23" r="7" class="color3"/>
<circle cx="64" cy="23" r="7" class="color2"/>
<svg id="screen" width="656" height="323" x="23" y="50" viewBox="0 0 656 323" preserveAspectRatio="xMidYMin slice"></svg>
</svg>

After

Width:  |  Height:  |  Size: 1.8 KiB