Polykey-Docs: Flesh out Polykey-CLI Tutorials "Getting Started"

[CMCDragonkai]

This tutorial should provide a run through of Polykey's functionality. It needs to start from the begnning beginning of using PK and provide a practical outcome with using PK.

PR to track Tasks #6-9 -> #72

Tasks

• 0. Revamp Readme.md of polykey-cli
• 1. Revamp docs/tutorials/polykey-cli to outline the "getting started" pages that fall under this section - Polykey-Docs CLI Tutorial: Add Getting Started Section  #52
• 2. Installation Section
• 3. Bootstrapping Polykey-Docs CLI Tutorial: Bootstrapping Keypair  #53 - Will need to do a re-check ~ 15 min
• 4. Managing Vaults Polykey-Docs CLI Tutorial: Managing Vaults  #54 - Will need to do some reformatting to match Managing secret's ~45 min
• 5. Managing Secrets Polykey-Docs CLI Tutorial: Managing Secrets  #55
  - We can provide an example of injecting secrets into the environment here
• 6. Claiming Identity Polykey-Docs CLI Tutorial: Claiming Digital identities  #56 -> ~1 hour
• 7. Connecting to other Nodes Polykey-Docs CLI Tutorial: Connecting to Other Nodes  #57 - What if you have no friends? - ~2.5 hours Let's make up a friend. By creating a 2nd node (for a separate node path) locally. In this case, both nodes will claim the same identity, so then you're sharing a vault between your own nodes.
• 8. Sharing Vaults Polykey-Docs CLI Tutorial: Sharing Vaults  #58 - ~3 hours
• Share Vault with 2nd node
• 9. Secrets ENV command Polykey-Docs CLI Tutorial: ENV Command  #59~ ~2 hours

Once all these pages have been completed. We can push. However, the flow from page-to-page varies somewhat and i'd like to use a more consistent approach so it will require a revamp ticket after this.

[CMCDragonkai]

Doing this may require using the crypto upgrade branch first for keys related operations, then using the staging branch for other operations if the crypto upgrade branch is still broken.

[CMCDragonkai]

So in feature-tutorials, I've set up the tutorials index page and rewritten the home page.

Following docusaurus documentation I realised I should have an installation under tutorials.

Here we will have to go over how to install each thing.

* [Polykey Core Library](https://github.com/MatrixAI/Polykey)
* [Polykey CLI](https://github.com/MatrixAI/Polykey-CLI)
* [Polykey Desktop](https://github.com/MatrixAI/Polykey-Desktop)
* [Polykey Mobile](https://github.com/MatrixAI/Polykey-Mobile)

Then we can get the getting started setup.

[CMCDragonkai]

I've setup category pages as part of this work. So that now each "category" is has their own page. For example ./src/docs/tutorials/README.md is actually https://polykey.io/docs/tutorials. It's a custom markdown page, but it's actually MDX because docusaurus supports it. However I don't think GitHub can render MDX, so I'm just keeping the extension as MD.

[CMCDragonkai]

[CMCDragonkai]

The installation page https://polykey.io/docs/tutorials/installation has been done and deployed. This is not exactly the Getting Started. But I'd like to have a working CLI right now. Maybe using the staging branch while synthesising changes from the feature-crypto.

To be continued.

[CMCDragonkai]

This should talk about:

• Bootstrapping
• Keys
• Agent Status
• Storing and Retrieving Secrets in the Vault
• And connecting to the P2P testnet and mainnet

[amydevs]

@CMCDragonkai
For connecting to the testnet, I'm getting warnings when running

pk agent start --network testnet
# or setting the seednode to the one defined in config.ts and used in testnet tests
pk agent start --seed-nodes vg9a9e957878s2qgtbdmu2atvli8ms7muukb1dk4dpbm4llkki3h0@testnet.polykey.io:1314

The warnings in question:

WARN:polykey.PolykeyAgent.Proxy.ConnectionForward 52.65.240.37:1314:Forward Error: ErrorConnectionEndTimeout
WARN:polykey.PolykeyAgent.Proxy.ConnectionForward 52.62.176.59:1314:Forward Error: ErrorConnectionEndTimeout

[CryptoTotalWar]

User Flow Analysis

1. User clicks on Docs and is directed to the Home Page of Polykey Docs http://localhost:3000/docs/

2. How easy is it for the user to navigate to the section of documentation for "getting started" ?

Intuitively, from the 4 high-level section laid out in the Divio system, the Tutorials section seems like the most intuitive plays to click next. This bring the user to the following page:

However, as i've mentioned previously,

• Polykey Desktop & Polykey Mobile should be removed from the sidebats.ts and hidden because until we have the actual application for these, they just add noise and confusion as at the moment, we just want to direct user attention to Polykey CLI and Polykey Core.

3. When a user clicks on Polykey CLI they are guided to the following page:
   

• I think on this page, we should repurpose one of the bottom sections (for example where the warning message is) with a headline as "getting started" because all the pages that a user needs to navigate through in chronological order is listed here:
  

4. First section is installation, second section is bootstrapping Keypair, third section is Managing Vaults, 4th section is managing secrets, 5th section should be claiming digital identities, 6th section should be connecting to other nodes, 7th section should be sharing vaults. Maybe last section should be the .env command.

@CMCDragonkai Should the section laid out in number 4 be sufficient for a getting started guide under tutorials for Polykey CLI ?

[CMCDragonkai]

@CryptoTotalWar this is an issue for creating a getting started page. It is not for the design of the docs linking.

[CryptoTotalWar]

Exactly, instead of 1 page for getting started, I think it should be a breakdown of multiple pages covering the various concepts of the PK CLI. similar to what's covered in the Demo video where the Polykey CLI page will be a high-level overview quickly outlining the breakdown that the sub-pages will go through and guide the user in getting started.

[CryptoTotalWar]

https://infisical.com/docs/documentation/getting-started/introduction

Reference this doc style for ideas with overall structure when feeling blocked on this.

[CMCDragonkai]

This is going to be broken down into sub-issues - and each one should be completed within a cycle. If this takes longer than 1 cycle, it should be broken down.

[CMCDragonkai]

Otherwise it doesn't make sense to keep this in 1 cycle. Unless you're doing this 1 task at a time.

[CryptoTotalWar]

All sub-issues have been added and updated on Linear.

[CMCDragonkai]

Please review my #33 to see if I had content that wasn't published aiming at this.

[CMCDragonkai]

Cycle 2, this is still relevant and highest priority.

[CMCDragonkai]

This is the main to focus on on.

[CMCDragonkai]

This week - was meant for this!

[CMCDragonkai]

For the reference docs of polykey-core, just leave this myself. I'll organise this with @amydevs and @tegefaulkes later, see: #61 (comment)

[CMCDragonkai]

This should be the main priority for cycle 2. More so than the blog post! You got all of the necessary info for all the getting started, you've already done it for real with multiple people when demoing PK, so just focus on this, and push to staging.

[CMCDragonkai]

For 8. Sharing Vaults you can share vault between 2 local nodes, you just need a second node on a different local path.

[CMCDragonkai]

For 9. if you are injecting secrets keep it simple to avoid doubling up with the how to guide.

[CMCDragonkai]

I think for 9. that can just embed into Managing Secrets.

[CMCDragonkai]

I've fleshed out some details in Bootstrapping atm, primarily to:

1. Distinguish node vs agent
2. Ensure that the initial setup is really about creating the root key (I purposely left out alot of detail regarding the exact specifics of the root key generation, as it's quite complicated, and needs to bring the excalidraw stuff regarding this later)
3. Specifically mentioning the usage of the mainnet dashboard https://mainnet.polykey.com
4. Adding --verbose to the starting to aid in people seeing errors and giving us useful debug when they first start up.

[CMCDragonkai]

Replacing alot of the CLI commands with asciicast would be nicer and make it easier to understand.

But doing it on Mac is a bit of a pain, as you do need a proper PS1 template for ZSH. From there then using asciicast and the conversion to gif would be useful.

Actually it makes sense to keep it as the regular asciicast player - hosted on asciicast as it remains searchable information rather than a gif.

So I would keep any written commands, and then do a asciicast summary at the very end - with a standard embed from asciicast. But I will want to setup a Matrix AI account there (as an official cast account) - or if we can embed an asciicast player...

[CryptoTotalWar]

https://docs.divio.com/documentation-system/tutorials/

https://www.conventionalcommits.org/en/v1.0.0/

To make sure we have a good mastery of these subjects going forward.

[CryptoTotalWar]

Going to wrap up secrets env doc with utilizing the same demo i did in the blog posts and by building on the concept of multiple nodes so they can see:

User A has a repo with pk env config.

User A has node A with vault A.

User A sends Vault A to user B/A with Node B.

User B clones User A's repo and runs npm start with the vault in their node.