21. February 2023

[dimakuv]

Agenda

(please write your proposed agenda items in comments under this discussion)

• Dmitrii (and Sankar if available): agree on the API for gsc sign-image plugins: Sankar's take is Enable --template option to use with sign-image (for use with HSMs, for example) gsc#112 and Change positional args manifest and key to optional args gsc#118.
• Benny Fuhry and Paul Cartee: current state of documentation restructuring.

Current state of documentation restructuring

Benny: gives historical context. Paul Cartee took over the job of restructuring Gramine documentation.

Paul: overview of Gramine kinds of usage:

1. Ready-made protected apps
2. Protecting containers
3. Protecting apps

Benny: we start with the easiest usage to the hardest.

• Mona: is it good? People may look at "ready-made apps", not find what they are looking for, and walk away. Not understanding that Gramine is "broad" -- theoretically running any Linux app.

Woju: ReadTheDocs is typically for technical documentation, but this restructuring is more for a web-site (which surely needs fixing).

• Mona: the web-site will happen... but not sure when?
• Woju: ReadTheDocs documentation is located in our core GitHub repo. If someone wants to add information on e.g. new examples or third-party solutions, it doesn't seem to be a right place. Again, this should be on the web page.

More detailed comments:

• Woju: I like the "Contribute to Gramine" and "Resources" sections.

• Woju: instead of "Set up Gramine environment", we need a separate page with "Requirements" (before "Gramine installation").

• Benny: the next step would be to rebase the "restructured" documentation to the latest state of docs.

  • Woju: how does Paul want to submit this restructuring? He creates a PR and then amends it based on reviews?
  • Paul: I'll need some help with creating a PR.
    • Dmitrii: The simplest way would be for one of Gramine devs (like me) to copy-paste the text from restructured docs on top of the current docs state.
    • Mona and Woju: we don't care about the history of "restructured" documentation changes, we can just squash all that in one commit (well, even just create from scratch).

• TODO: Woju will send the git-diff of all changes in core Gramine repo since September to Benny and Paul, and they can incorporate those changes. [DONE]

API for gsc sign-image plugins

Sankar's proposal: gramineproject/gsc#112
Woju's proposal: #1118

Woju: the problem is with GSC itself -- its architecture is upside down. GSC starts with an app image, then adds Gramine, then signing via a separate Dockerfile. It should have been different: GSC starts with a Gramine image (maybe augmented with all these plugins), then adds the app into it.

• So GSC arch should be actually reverted for Woju's signing plugin design to work nicely.

• We did something like that 5 years ago at ITL for a customer, and it worked nicely (Michal did it).

• Mona: I don't think we can change GSC because people want to run "graminized unmodified containers", not create new containers on top of Gramine one.

• Dmitrii: we side-tracked completely. We shouldn't discuss the completely different tool, when our topic is "how to add custom signing"?

• Woju: maybe just add all those enclave-signing Dockerfile templates into GSC repo directly? This seems to be the least "hacky" approach.

  • So then PRs Add AKV Dockerfile templates for signing with gsc contrib#20 and Add SGX enclave signing with OpenSSL engine contrib#19 should be recreated in GSC (just like Sankar originally planned with: Add support for production signing with Azure Key Vault gsc#108).
  • TODO: Woju will give his feedback on those PRs. [DONE]
  • TODO: Woju will also give feedback on Change positional args manifest and key to optional args gsc#118 (uniform handling of GSC args).

[mkow]

I had to miss the call, so I'll ask my questions here.

Woju: ReadTheDocs is typically for technical documentation, but this restructuring is more for a web-site (which surely needs fixing).

* _Mona_: the web-site will happen... but not sure when?

* _Woju_: ReadTheDocs documentation is located in our core GitHub repo. If someone wants to add information on e.g. new examples or third-party solutions, it doesn't seem to be a right place. Again, this should be on the web page.

@woju: Could you be more precise with which parts of the restructuring doesn't suit the RTD and why?

[woju]

1. the order of the blue headers in the menu: it's good for CTA on landing page, bad for technical docs (on tech docs, the first thing should be direct installation from signed repos, and on landing page, the first thing should be evaluation from ready-made containers); hence I'd see it more in gramineproject.io than on RTD. Moreover, "Ready-made protected applications" should be documented where they live, i.e. in contrib.
2. We also talked a bit about what currently is "Users of gramine" and this marketingspeak (do you remember when we slashed half of one submission, because the full paragraph contained literally 0 content?). I think it has no place on RTD, but it perfectly fits a carousel or sth on landing page.

Also it's generally better to move third party stuff to gramineproject.io because 1) it doesn't sync with our current repo [and esp. /en/stable on RTFD — this detail I didn't mention in the call], 2) it subtracts from the review bandwidth and the review is set up for technical things (hence our 2-of-3 orga rules etc.)

That's what I remember from the call.

[mkow]

it's [...] bad for technical docs

Why? I think I like the proposed order, you get instructions grouped by your use-case, which seems useful - you can find straight what you need.

"Ready-made protected applications" should be documented where they live

We should drop this part mostly because these are not suitable for production in the current shape.

We also talked a bit about what currently is "Users of gramine" and this marketingspeak (do you remember when we slashed half of one submission, because the full paragraph contained literally 0 content?). I think it has no place on RTD, but it perfectly fits a carousel or sth on landing page.

+1, I think this should be moved out of the docs to the website, it doesn't have any value in the documentation and the quality of the descriptions there was rather questionable.