docs: embedd asciinema casts

[datosh]

Signed-off-by: Fabian Kammel fk@edgeless.systems

Proposed change(s)

• Move Dockerfile and scripts to generate casts from https://github.com/edgelesssys/screenrecordings to monorepo so we can generate everything from start to finish
• Use asciinema-player to directly embedd asciinema casts into our docs (without rendering them as mp4).
  • Use termtosvg to convert a .cast file to svg to display in GitHub README.md, since it does not support JavaScript.
• Updated workflows for SBOM & CLI verification
• Added new workflows for create config, delete IAM, create cluster, destroy cluster.
• Documented process and how to style elements of screen casts.

Open Questions

• With this solution, are mp4 renderings of the screencast still necessary? For example to upload them to YouTube?
  • No, we will record sessions with OBS if we intend to record webinar style sessions.
• Should the user run generate-screencasts.sh or should the pipeline do this? I lean to the former, since the output needs to be inspected and docs preview is currently broken.
  • It is fine to make the user run this.

Additional info

• Please try to generate screencasts from your machine and let me know how it goes. Everything is in containers / shell scripts, but it would be great to confirm it works on another system as well!
• Currently we still have the spinner in our screencasts. Since the screencasts simulate what a user would do (download an actual released Constellation CLI) we need to re-run screencast generation once v2.6.0 is released.

Checklist

• Update docs
• Add labels (e.g., for changelog category)
• Link to Milestone

[netlify]

✅ Deploy Preview for constellation-docs ready!

Name	Link
🔨 Latest commit	e9225be
🔍 Latest deploy log	https://app.netlify.com/sites/constellation-docs/deploys/640bb855133f970008b0b232
😎 Deploy Preview	https://deploy-preview-1154--constellation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[m1ghtym0]

Perfect, this is exactly what I had in mind initially when scripting the asciinema recordings:-)
Makes it easy to manage any additions/changes and keep everything consistent with our docs.
For YT we can do longer "webinars" that we record with OBS.

[thomasten]

I like it this way, too!

[datosh]

For those who just want to have a quick peek, it currently looks like this:

[thomasten]

Mostly looks good to me, but I'm not very experienced with some of the technologies used in this PR ;)
There could be a bit more space between the widget and the text below. It looks good when inserting a <br/>, but I'm quite sure this isn't the correct way to do it :D

[datosh]

Mostly looks good to me, but I'm not very experienced with some of the technologies used in this PR ;)

Same here 😆 so getting a 👍 already helps. Thanks! I checked with @flxflx , and the goal should be to get this to "good enough" until someone with more CSS/design experience can do a second pass! There are probably ways to get this done cleaner, but I am mostly confident that this should be stable and flexible enough for what we use it for.

I added a horizontal line below the screencast and an info box above. I also tried to match the font size more closely to what the docs already have.

I will keep the technical part as it is and work on scripting the other workflows in our docs.

[datosh]

Automated creation of screen recordings for documentation is implemented. I have created / updated the recordings. I think additional recordings should be tackled in their own PR so we can get this one to the finish line.

When working on the recordings I noticed the following points, I will clarify with the CC'd folks:

• constellation iam create gcp --generate-config ... makes the user manually insert project, region & zone into config, although they are already provided to iam create. Could we fill these values automatically? @msanft
• Terminate docs regarding terraform.tfstate are outdated. What is the correct update? @msanft
• The spinner breaks the automatic skipping feature of asciinema. Is there an easy way to disable spinner? debug will disable the spinner but enable too verbose output. @daniel-weisse
  • Piping stderr to a file in expect/asciinema seems to be too hacky.
  • Automated asciinema setup requires tty

[msanft]

Could we fill these values automatically?

Missing GCP region values are / were a bug and have been addressed in #1149.

Terminate docs regarding terraform.tfstate are outdated.

This looks good to me at first glance. What is the exact issue? Or are you not talking about IAM termination / deletion?

[datosh]

Could we fill these values automatically?

Missing GCP region values are / were a bug and have been addressed in #1149.

Awesome! I will rebase to include the changes 🙂

Terminate docs regarding terraform.tfstate are outdated.

This looks good to me at first glance. What is the exact issue? Or are you not talking about IAM termination / deletion?

I should have been more specific. I was thrown off by: "You can terminate your cluster using the CLI. For this, you need the Terraform state file named terraform.tfstate in the current directory." in terminate docs.

[msanft]

I should have been more specific. I was thrown off by: "You can terminate your cluster using the CLI. For this, you need the Terraform state file named terraform.tfstate in the current directory." in terminate docs.

I addressed that in #1212 - let me know if this is the change you expected. I wasn't entirely sure as I didn't write that part of the docs nor was involved with the termination command.

[datosh]

Ready for final review: please see updated PR description.

[m1ghtym0]

I verified locally on my machine, and everything worked fine!
This is awesome! Once, we have 2.6 without the spinner version, I'll rerun the current set of casts

[thomasten]

Nice! Pls publish docs to 2.6 and then it should be ready to merge.

[thomasten]

delete file