From d0d2d0d06d2a24a455d129f1c54d90322b76bcde Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Sun, 7 Jul 2024 18:57:54 -0500 Subject: [PATCH 01/23] rename Tutorials category to Getting-Started --- sidebars.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.ts b/sidebars.ts index 7b251807..1095f44f 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,7 +4,7 @@ const sidebars: SidebarsConfig = { docs: [ { type: 'category', - label: 'Tutorials', + label: 'Getting Started', collapsed: false, link: { type: 'doc', From 924430ab8a7c1556d075c2e7b7f51891ee9adb4e Mon Sep 17 00:00:00 2001 From: Ihtsham Shafiq Date: Mon, 8 Jul 2024 10:54:30 +1000 Subject: [PATCH 02/23] fix: add labels and remove parent containers --- sidebars.ts | 151 ++++++++++++++++++++++++---------------------------- 1 file changed, 70 insertions(+), 81 deletions(-) diff --git a/sidebars.ts b/sidebars.ts index 1095f44f..3c5b63fa 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2,103 +2,92 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { docs: [ + { + type: 'html', + value: 'Getting Started', // The HTML to be rendered + defaultStyle: true, // Use the default menu item styling + }, { type: 'category', - label: 'Getting Started', - collapsed: false, + label: 'Polykey CLI', link: { type: 'doc', - id: 'tutorials/README', + id: 'tutorials/polykey-cli/README', }, items: [ - { - type: 'category', - label: 'Polykey CLI', - link: { - type: 'doc', - id: 'tutorials/polykey-cli/README', - }, - items: [ - 'tutorials/polykey-cli/installation', - 'tutorials/polykey-cli/bootstrapping', - 'tutorials/polykey-cli/managing-vaults', - 'tutorials/polykey-cli/managing-secrets', - 'tutorials/polykey-cli/claiming-digital-identities', - 'tutorials/polykey-cli/discovering-other-users', - 'tutorials/polykey-cli/sharing-vaults', - 'tutorials/polykey-cli/managing-multiple-nodes', - 'tutorials/polykey-cli/using-environment-variables', - ], - }, - { - type: 'category', - label: 'Polykey Desktop', - link: { - type: 'doc', - id: 'tutorials/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Mobile', - link: { - type: 'doc', - id: 'tutorials/polykey-mobile/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Core', - link: { - type: 'doc', - id: 'tutorials/polykey-core/README', - }, - items: ['tutorials/polykey-core/installation'], - }, + 'tutorials/polykey-cli/installation', + 'tutorials/polykey-cli/bootstrapping', + 'tutorials/polykey-cli/managing-vaults', + 'tutorials/polykey-cli/managing-secrets', + 'tutorials/polykey-cli/claiming-digital-identities', + 'tutorials/polykey-cli/discovering-other-users', + 'tutorials/polykey-cli/sharing-vaults', + 'tutorials/polykey-cli/managing-multiple-nodes', + 'tutorials/polykey-cli/using-environment-variables', ], }, { type: 'category', - label: 'How To Guides', - collapsed: false, + label: 'Polykey Desktop', link: { type: 'doc', - id: 'how-to-guides/README', + id: 'tutorials/polykey-desktop/README', }, + items: [], + }, + { + type: 'category', + label: 'Polykey Mobile', + link: { + type: 'doc', + id: 'tutorials/polykey-mobile/README', + }, + items: [], + }, + { + type: 'category', + label: 'Polykey Core', + link: { + type: 'doc', + id: 'tutorials/polykey-core/README', + }, + items: ['tutorials/polykey-core/installation'], + }, + { + type: 'html', + value: 'How To Guides', // The HTML to be rendered + defaultStyle: true, // Use the default menu item styling + }, + { + type: 'category', + label: 'Developers', + items: ['how-to-guides/developers/development-environment-secrets'], + }, + { + type: 'category', + label: 'DevOps', items: [ - { - type: 'category', - label: 'Developers', - items: ['how-to-guides/developers/development-environment-secrets'], - }, - { - type: 'category', - label: 'DevOps', - items: [ - 'how-to-guides/devops/service-deployment-secrets-with-aws-ecs', - 'how-to-guides/devops/cloud-agnostic-secrets-management', - 'how-to-guides/devops/ci-cd-secrets-with-gitlab', - 'how-to-guides/devops/microservice-authentication-with-zero-trust-and-mtls', - ], - }, - { - type: 'category', - label: 'Companies and Teams', - items: [ - 'how-to-guides/companies-and-teams/employee-onboarding-and-offboarding', - 'how-to-guides/companies-and-teams/device-provisioning', - 'how-to-guides/companies-and-teams/delegation-of-authority', - ], - }, - { - type: 'category', - label: 'General', - items: ['how-to-guides/general/cryptocurrency-wallet'], - }, + 'how-to-guides/devops/service-deployment-secrets-with-aws-ecs', + 'how-to-guides/devops/cloud-agnostic-secrets-management', + 'how-to-guides/devops/ci-cd-secrets-with-gitlab', + 'how-to-guides/devops/microservice-authentication-with-zero-trust-and-mtls', ], }, + { + type: 'category', + label: 'Companies and Teams', + items: [ + 'how-to-guides/companies-and-teams/employee-onboarding-and-offboarding', + 'how-to-guides/companies-and-teams/device-provisioning', + 'how-to-guides/companies-and-teams/delegation-of-authority', + ], + }, + { + type: 'category', + label: 'General', + items: ['how-to-guides/general/cryptocurrency-wallet'], + }, + { type: 'category', label: 'Theory', From c2338f7d7ce6e1cd4257979e0d55ca0580b24550 Mon Sep 17 00:00:00 2001 From: Ihtsham Shafiq Date: Mon, 8 Jul 2024 12:20:22 +1000 Subject: [PATCH 03/23] fix: fixed build, restructured folders, removed category link --- .../polykey-cli/README.md | 0 .../polykey-cli/bootstrapping.md | 0 .../claiming-digital-identities.md | 0 .../polykey-cli/discovering-other-users.md | 0 .../polykey-cli/installation.md | 0 .../polykey-cli/managing-multiple-nodes.md | 0 .../polykey-cli/managing-secrets.md | 0 .../polykey-cli/managing-vaults.md | 0 .../polykey-cli/sharing-vaults.md | 0 .../using-environment-variables.md | 0 .../polykey-core/README.md | 0 .../polykey-core/installation.md | 0 .../polykey-desktop/README.md | 0 .../polykey-mobile/README.md | 0 docs/tutorials/README.md | 11 -- sidebars.ts | 153 +++++++++--------- 16 files changed, 80 insertions(+), 84 deletions(-) rename docs/{tutorials => getting-started}/polykey-cli/README.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/bootstrapping.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/claiming-digital-identities.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/discovering-other-users.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/installation.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/managing-multiple-nodes.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/managing-secrets.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/managing-vaults.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/sharing-vaults.md (100%) rename docs/{tutorials => getting-started}/polykey-cli/using-environment-variables.md (100%) rename docs/{tutorials => getting-started}/polykey-core/README.md (100%) rename docs/{tutorials => getting-started}/polykey-core/installation.md (100%) rename docs/{tutorials => getting-started}/polykey-desktop/README.md (100%) rename docs/{tutorials => getting-started}/polykey-mobile/README.md (100%) delete mode 100644 docs/tutorials/README.md diff --git a/docs/tutorials/polykey-cli/README.md b/docs/getting-started/polykey-cli/README.md similarity index 100% rename from docs/tutorials/polykey-cli/README.md rename to docs/getting-started/polykey-cli/README.md diff --git a/docs/tutorials/polykey-cli/bootstrapping.md b/docs/getting-started/polykey-cli/bootstrapping.md similarity index 100% rename from docs/tutorials/polykey-cli/bootstrapping.md rename to docs/getting-started/polykey-cli/bootstrapping.md diff --git a/docs/tutorials/polykey-cli/claiming-digital-identities.md b/docs/getting-started/polykey-cli/claiming-digital-identities.md similarity index 100% rename from docs/tutorials/polykey-cli/claiming-digital-identities.md rename to docs/getting-started/polykey-cli/claiming-digital-identities.md diff --git a/docs/tutorials/polykey-cli/discovering-other-users.md b/docs/getting-started/polykey-cli/discovering-other-users.md similarity index 100% rename from docs/tutorials/polykey-cli/discovering-other-users.md rename to docs/getting-started/polykey-cli/discovering-other-users.md diff --git a/docs/tutorials/polykey-cli/installation.md b/docs/getting-started/polykey-cli/installation.md similarity index 100% rename from docs/tutorials/polykey-cli/installation.md rename to docs/getting-started/polykey-cli/installation.md diff --git a/docs/tutorials/polykey-cli/managing-multiple-nodes.md b/docs/getting-started/polykey-cli/managing-multiple-nodes.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-multiple-nodes.md rename to docs/getting-started/polykey-cli/managing-multiple-nodes.md diff --git a/docs/tutorials/polykey-cli/managing-secrets.md b/docs/getting-started/polykey-cli/managing-secrets.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-secrets.md rename to docs/getting-started/polykey-cli/managing-secrets.md diff --git a/docs/tutorials/polykey-cli/managing-vaults.md b/docs/getting-started/polykey-cli/managing-vaults.md similarity index 100% rename from docs/tutorials/polykey-cli/managing-vaults.md rename to docs/getting-started/polykey-cli/managing-vaults.md diff --git a/docs/tutorials/polykey-cli/sharing-vaults.md b/docs/getting-started/polykey-cli/sharing-vaults.md similarity index 100% rename from docs/tutorials/polykey-cli/sharing-vaults.md rename to docs/getting-started/polykey-cli/sharing-vaults.md diff --git a/docs/tutorials/polykey-cli/using-environment-variables.md b/docs/getting-started/polykey-cli/using-environment-variables.md similarity index 100% rename from docs/tutorials/polykey-cli/using-environment-variables.md rename to docs/getting-started/polykey-cli/using-environment-variables.md diff --git a/docs/tutorials/polykey-core/README.md b/docs/getting-started/polykey-core/README.md similarity index 100% rename from docs/tutorials/polykey-core/README.md rename to docs/getting-started/polykey-core/README.md diff --git a/docs/tutorials/polykey-core/installation.md b/docs/getting-started/polykey-core/installation.md similarity index 100% rename from docs/tutorials/polykey-core/installation.md rename to docs/getting-started/polykey-core/installation.md diff --git a/docs/tutorials/polykey-desktop/README.md b/docs/getting-started/polykey-desktop/README.md similarity index 100% rename from docs/tutorials/polykey-desktop/README.md rename to docs/getting-started/polykey-desktop/README.md diff --git a/docs/tutorials/polykey-mobile/README.md b/docs/getting-started/polykey-mobile/README.md similarity index 100% rename from docs/tutorials/polykey-mobile/README.md rename to docs/getting-started/polykey-mobile/README.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md deleted file mode 100644 index 70771834..00000000 --- a/docs/tutorials/README.md +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Tutorials - -The tutorials here are recommended as an introduction to the Polykey ecosystem. - -They allow you to get started using Polykey in a practical manner. - -Each tutorial is categorized under a particular subproject. - - diff --git a/sidebars.ts b/sidebars.ts index 3c5b63fa..07f8c2fe 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2,92 +2,99 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { docs: [ - { - type: 'html', - value: 'Getting Started', // The HTML to be rendered - defaultStyle: true, // Use the default menu item styling - }, { type: 'category', - label: 'Polykey CLI', - link: { - type: 'doc', - id: 'tutorials/polykey-cli/README', - }, + label: 'Getting Started', + collapsed: false, items: [ - 'tutorials/polykey-cli/installation', - 'tutorials/polykey-cli/bootstrapping', - 'tutorials/polykey-cli/managing-vaults', - 'tutorials/polykey-cli/managing-secrets', - 'tutorials/polykey-cli/claiming-digital-identities', - 'tutorials/polykey-cli/discovering-other-users', - 'tutorials/polykey-cli/sharing-vaults', - 'tutorials/polykey-cli/managing-multiple-nodes', - 'tutorials/polykey-cli/using-environment-variables', + { + type: 'category', + label: 'Polykey CLI', + link: { + type: 'doc', + id: 'getting-started/polykey-cli/README', + }, + items: [ + 'getting-started/polykey-cli/installation', + 'getting-started/polykey-cli/bootstrapping', + 'getting-started/polykey-cli/managing-vaults', + 'getting-started/polykey-cli/managing-secrets', + 'getting-started/polykey-cli/claiming-digital-identities', + 'getting-started/polykey-cli/discovering-other-users', + 'getting-started/polykey-cli/sharing-vaults', + 'getting-started/polykey-cli/managing-multiple-nodes', + 'getting-started/polykey-cli/using-environment-variables', + ], + }, + { + type: 'category', + label: 'Polykey Desktop', + link: { + type: 'doc', + id: 'getting-started/polykey-desktop/README', + }, + items: [], + }, + { + type: 'category', + label: 'Polykey Mobile', + link: { + type: 'doc', + id: 'getting-started/polykey-mobile/README', + }, + items: [], + }, + { + type: 'category', + label: 'Polykey Core', + link: { + type: 'doc', + id: 'getting-started/polykey-core/README', + }, + items: ['getting-started/polykey-core/installation'], + }, ], }, { type: 'category', - label: 'Polykey Desktop', - link: { - type: 'doc', - id: 'tutorials/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Mobile', - link: { - type: 'doc', - id: 'tutorials/polykey-mobile/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Core', + label: 'How To Guides', + collapsed: false, link: { type: 'doc', - id: 'tutorials/polykey-core/README', + id: 'how-to-guides/README', }, - items: ['tutorials/polykey-core/installation'], - }, - { - type: 'html', - value: 'How To Guides', // The HTML to be rendered - defaultStyle: true, // Use the default menu item styling - }, - { - type: 'category', - label: 'Developers', - items: ['how-to-guides/developers/development-environment-secrets'], - }, - { - type: 'category', - label: 'DevOps', - items: [ - 'how-to-guides/devops/service-deployment-secrets-with-aws-ecs', - 'how-to-guides/devops/cloud-agnostic-secrets-management', - 'how-to-guides/devops/ci-cd-secrets-with-gitlab', - 'how-to-guides/devops/microservice-authentication-with-zero-trust-and-mtls', - ], - }, - { - type: 'category', - label: 'Companies and Teams', items: [ - 'how-to-guides/companies-and-teams/employee-onboarding-and-offboarding', - 'how-to-guides/companies-and-teams/device-provisioning', - 'how-to-guides/companies-and-teams/delegation-of-authority', + { + type: 'category', + label: 'Developers', + items: ['how-to-guides/developers/development-environment-secrets'], + }, + { + type: 'category', + label: 'DevOps', + items: [ + 'how-to-guides/devops/service-deployment-secrets-with-aws-ecs', + 'how-to-guides/devops/cloud-agnostic-secrets-management', + 'how-to-guides/devops/ci-cd-secrets-with-gitlab', + 'how-to-guides/devops/microservice-authentication-with-zero-trust-and-mtls', + ], + }, + { + type: 'category', + label: 'Companies and Teams', + items: [ + 'how-to-guides/companies-and-teams/employee-onboarding-and-offboarding', + 'how-to-guides/companies-and-teams/device-provisioning', + 'how-to-guides/companies-and-teams/delegation-of-authority', + ], + }, + { + type: 'category', + label: 'General', + items: ['how-to-guides/general/cryptocurrency-wallet'], + }, ], }, - { - type: 'category', - label: 'General', - items: ['how-to-guides/general/cryptocurrency-wallet'], - }, - { type: 'category', label: 'Theory', From ed9ccd2029c75b84b26c360fa3ea78e12b45a201 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Mon, 8 Jul 2024 11:26:16 -0500 Subject: [PATCH 04/23] updated the source path --- docs/README.md | 2 +- docs/getting-started/polykey-cli/README.md | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index f2163de6..cf37266a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ Welcome to the Polykey documentation. The documentation is structured using [Divio system](https://documentation.divio.com/). -- [Tutorials](./tutorials) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome +- [Tutorials](./getting-started) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome - [How-To Guides](/docs/how-to-guides) - these are short guides on how to achieve a specific use-case which makes assumptions on the reader - [Theory](./theory/) - these are important for understanding the "why" of Polykey - [Reference](./reference/) - these are useful when you need remember how to use a particular command or function diff --git a/docs/getting-started/polykey-cli/README.md b/docs/getting-started/polykey-cli/README.md index c254b95b..43fb16a2 100644 --- a/docs/getting-started/polykey-cli/README.md +++ b/docs/getting-started/polykey-cli/README.md @@ -35,15 +35,15 @@ Start your journey with Polykey by following the tutorials below in sequence: For a visual walkthrough, check out our [getting started demo video](https://vimeo.com/884649667) after installing Polykey. ::: -1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install Polykey CLI on your platform. -2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)** - Set up your node and connect to the network. -3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)** - Securely store secrets within encrypted vaults. -4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)** - Organize and handle secrets within your vaults. -5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)** - Establish and authenticate your identity within the network. -6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)** - Find and verify other users to manage permissions. -7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)** - Share your encrypted vaults securely with peers. -8. **[Managing Multiple Nodes](/docs/tutorials/polykey-cli/managing-multiple-nodes)** - Operate multiple local nodes/agents. -9. **[Using Environment Variables](/docs/tutorials/polykey-cli/using-environment-variables)** - Master `polykey secrets env` for dynamic environment management. +1. **[Installation](/docs/getting-started/polykey-cli/installation)** - Install Polykey CLI on your platform. +2. **[Bootstrap Keypair](/docs/getting-started/polykey-cli/bootstrapping)** - Set up your node and connect to the network. +3. **[Managing Vaults](/docs/getting-started/polykey-cli/managing-vaults)** - Securely store secrets within encrypted vaults. +4. **[Managing Secrets](/docs/getting-started/polykey-cli/managing-secrets)** - Organize and handle secrets within your vaults. +5. **[Claiming Digital Identities](/docs/getting-started/polykey-cli/claiming-digital-identities)** - Establish and authenticate your identity within the network. +6. **[Discovering Other User's Identities](/docs/getting-started/polykey-cli/discovering-other-users)** - Find and verify other users to manage permissions. +7. **[Sharing Vaults](/docs/getting-started/polykey-cli/sharing-vaults)** - Share your encrypted vaults securely with peers. +8. **[Managing Multiple Nodes](/docs/getting-started/polykey-cli/managing-multiple-nodes)** - Operate multiple local nodes/agents. +9. **[Using Environment Variables](/docs/getting-started/polykey-cli/using-environment-variables)** - Master `polykey secrets env` for dynamic environment management. Explore advanced scenarios in subsequent sections, including: From 97e70a9d517062e99ab3534ba5712a5556e3f107 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Mon, 8 Jul 2024 11:49:41 -0500 Subject: [PATCH 05/23] deleted pk-mobile & pk-desktop... until we have something more substantial to add for it, we should not have it in the deployed docs because it just serves as a distraction atm --- .../getting-started/polykey-desktop/README.md | 9 ----- docs/getting-started/polykey-mobile/README.md | 9 ----- docs/reference/polykey-desktop/README.md | 5 --- docs/reference/polykey-mobile/README.md | 5 --- sidebars.ts | 36 ------------------- 5 files changed, 64 deletions(-) delete mode 100644 docs/getting-started/polykey-desktop/README.md delete mode 100644 docs/getting-started/polykey-mobile/README.md delete mode 100644 docs/reference/polykey-desktop/README.md delete mode 100644 docs/reference/polykey-mobile/README.md diff --git a/docs/getting-started/polykey-desktop/README.md b/docs/getting-started/polykey-desktop/README.md deleted file mode 100644 index af7d379c..00000000 --- a/docs/getting-started/polykey-desktop/README.md +++ /dev/null @@ -1,9 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Desktop - -[Polykey Desktop](https://github.com/MatrixAI/Polykey-Desktop) is the desktop application providing a graphical user interface for interacting with the Polykey network. It is still currently under development. As of now, there are no tutorials for Polykey Desktop. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Desktop). - - diff --git a/docs/getting-started/polykey-mobile/README.md b/docs/getting-started/polykey-mobile/README.md deleted file mode 100644 index 698807cd..00000000 --- a/docs/getting-started/polykey-mobile/README.md +++ /dev/null @@ -1,9 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Mobile - -[Polykey Mobile](https://github.com/MatrixAI/Polykey-Mobile) is the mobile application providing a graphical user interface for managing interactions with the Polykey network from your mobile device. It is still currently under development. As of now, there are no tutorials for Polykey Mobile. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Mobile). - - diff --git a/docs/reference/polykey-desktop/README.md b/docs/reference/polykey-desktop/README.md deleted file mode 100644 index c32c68e1..00000000 --- a/docs/reference/polykey-desktop/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey-Desktop - - diff --git a/docs/reference/polykey-mobile/README.md b/docs/reference/polykey-mobile/README.md deleted file mode 100644 index cd37bc93..00000000 --- a/docs/reference/polykey-mobile/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey-Mobile - - diff --git a/sidebars.ts b/sidebars.ts index 07f8c2fe..6af0c931 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -26,24 +26,6 @@ const sidebars: SidebarsConfig = { 'getting-started/polykey-cli/using-environment-variables', ], }, - { - type: 'category', - label: 'Polykey Desktop', - link: { - type: 'doc', - id: 'getting-started/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Mobile', - link: { - type: 'doc', - id: 'getting-started/polykey-mobile/README', - }, - items: [], - }, { type: 'category', label: 'Polykey Core', @@ -148,24 +130,6 @@ const sidebars: SidebarsConfig = { }, ], }, - { - type: 'category', - label: 'Polykey-Desktop', - link: { - type: 'doc', - id: 'reference/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey-Mobile', - link: { - type: 'doc', - id: 'reference/polykey-mobile/README', - }, - items: [], - }, { type: 'category', label: 'Polykey-Core', From 74fec8ebd9c919413034b5c9d7ec51d9c18ff6b8 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Tue, 9 Jul 2024 19:40:59 -0400 Subject: [PATCH 06/23] update insallation page location --- ...tallation.md => installing-polykey-cli.md} | 63 +++++++++++++------ sidebars.ts | 2 +- 2 files changed, 44 insertions(+), 21 deletions(-) rename docs/getting-started/{polykey-cli/installation.md => installing-polykey-cli.md} (89%) diff --git a/docs/getting-started/polykey-cli/installation.md b/docs/getting-started/installing-polykey-cli.md similarity index 89% rename from docs/getting-started/polykey-cli/installation.md rename to docs/getting-started/installing-polykey-cli.md index f477832c..8b91183c 100644 --- a/docs/getting-started/polykey-cli/installation.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -1,17 +1,55 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Installation +# Install Polykey-CLI + + + + + +The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. We designed the CLI user-experience (UX) to be suitable for a human operator, but also to be easily scripted and integrated into other tools. It is intended for developers and system administrators who require an advanced tool for managing secrets efficiently. + + Installing the CLI can be done in different ways depending on your operating environment. :::info -Polykey-CLI has only been tested on Linux and macOS. We are working on supporting other platforms. There's minor teething problems when it comes supporting other platforms. Help us by reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE). +Polykey-CLI is supported on all platforms but has only been tested on Linux and macOS. There's minor teething problems when it comes supporting multiple platforms. Help us by reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE). ::: + + + +:::note + +- NPM is the easiest most streamlined method that is preferred for installing the CLI. +- This requires having the latest version of node and npm installed. + +::: + +## Node Package Manager + +The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli). + +# Step 1 + +Install it with: + +```sh +npm install -g polykey-cli +``` + +This will install the Polykey-CLI into `$(npm config get prefix)`. + +If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`. + + + ## Linux @@ -152,6 +190,7 @@ and MacOS permits running of unsigned binaries, however, to progress past this, #### Method #1 - quickest method + The xattr command will remove the quarantine attribute from the polykey executable, allowing you to run it without triggering macOS security warnings. Remember to ensure that the file path matches the location of your polykey file. ```sh @@ -287,7 +326,7 @@ Polykey for windows should be working but we have yet to create documentation on - ## Docker +## Docker The Docker image can be used so that Polykey can be deployed into the cloud. It is also possible to use the CLI via the docker container, but it isn't as convenient. The intention is to run the Polykey agent in the cloud. @@ -368,23 +407,7 @@ recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly ``` - - -## Node Package Manager - -The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli). - -Install it with: - -```sh -npm install -g polykey-cli -``` - -This will install the Polykey-CLI into `$(npm config get prefix)`. - -If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`. - - + ## Source diff --git a/sidebars.ts b/sidebars.ts index 6af0c931..160778f6 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -7,6 +7,7 @@ const sidebars: SidebarsConfig = { label: 'Getting Started', collapsed: false, items: [ + 'getting-started/installing-polykey-cli', { type: 'category', label: 'Polykey CLI', @@ -15,7 +16,6 @@ const sidebars: SidebarsConfig = { id: 'getting-started/polykey-cli/README', }, items: [ - 'getting-started/polykey-cli/installation', 'getting-started/polykey-cli/bootstrapping', 'getting-started/polykey-cli/managing-vaults', 'getting-started/polykey-cli/managing-secrets', From 75c7dc9fece2b62932f4ec2f6f50a278e3e1bcf1 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Fri, 12 Jul 2024 18:04:56 +0100 Subject: [PATCH 07/23] add sidebar for /docs to getting started & update installation tutorial title --- docs/getting-started/installing-polykey-cli.md | 2 +- sidebars.ts | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index 8b91183c..b716527e 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Install Polykey-CLI +# Set Up Your First Polykey diff --git a/sidebars.ts b/sidebars.ts index 160778f6..c5bdf56d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -7,6 +7,11 @@ const sidebars: SidebarsConfig = { label: 'Getting Started', collapsed: false, items: [ + { + type: 'doc', + id: 'README', // This should match the path to your symlink + label: 'Welcome to Polykey Docs', // Label for the sidebar item + }, 'getting-started/installing-polykey-cli', { type: 'category', From ededd23c65e083f3457b918416b4ec5e3713c5ed Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Wed, 17 Jul 2024 11:12:48 +0100 Subject: [PATCH 08/23] WIP --- docs/README.md | 63 ++++++-- .../getting-started/installing-polykey-cli.md | 139 ++++++++++-------- sidebars.ts | 2 +- 3 files changed, 132 insertions(+), 72 deletions(-) diff --git a/docs/README.md b/docs/README.md index cf37266a..375d8da8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,16 +5,25 @@ displayed_sidebar: docs # Polykey Documentation -Welcome to the Polykey documentation. + -- [Tutorials](./getting-started) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome -- [How-To Guides](/docs/how-to-guides) - these are short guides on how to achieve a specific use-case which makes assumptions on the reader -- [Theory](./theory/) - these are important for understanding the "why" of Polykey -- [Reference](./reference/) - these are useful when you need remember how to use a particular command or function + + + ## Introduction @@ -30,10 +39,6 @@ Polykey helps yourself, teams and software agents to manage and share secrets in PolyKey is an open-source decentralised peer to peer secrets management system. It provides a software agent that runs on your device locally. Each agent process is a node in the Polykey peer to peer network. This agent manages your secret data and is capable of sharing secrets with other trusted Polykey agents. The secret data can be placed inside any directory on your computer including on USB storage. -## Features - -TBD - ## Principles There are 2 main concepts to understand in Polykey: @@ -71,6 +76,38 @@ As you deploy more Polykey agents, you can join existing gestalts. Your gestalt is how other users are able to share secrets with a trusted identity. Your identity is the sum of the reputation of all your digital identities that are part of the gestalt. -## Comparison to other Tools + + + diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index b716527e..9f9d5b8a 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -1,58 +1,55 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Set Up Your First Polykey - - - - +# Set-Up Polykey on your Machine +:::note The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. We designed the CLI user-experience (UX) to be suitable for a human operator, but also to be easily scripted and integrated into other tools. It is intended for developers and system administrators who require an advanced tool for managing secrets efficiently. +::: - +## Choose Your Installation Method for the Polykey-CLI -Installing the CLI can be done in different ways depending on your operating environment. + -:::info + -Polykey-CLI is supported on all platforms but has only been tested on Linux and macOS. There's minor teething problems when it comes supporting multiple platforms. Help us by reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE). +### Install using Node Package Manager -::: +The Polykey CLI is available as an [`npm` package](https://www.npmjs.com/package/polykey-cli). This method allows for easy installation across various operating systems using Node.js and npm. - +:::info - +#### System Requirements -:::note +Before installing, ensure your system meets the following requirements: -- NPM is the easiest most streamlined method that is preferred for installing the CLI. -- This requires having the latest version of node and npm installed. +- Node.js: Install the latest stable version of Node.js from nodejs.org +- npm (Node Package Manager): Comes with Node.js, but verify it’s updated by running `npm install -g npm` in your terminal. +- Environment Variables: Add the `npm` binary path to your system’s `$PATH` to run Polykey CLI from any terminal window. ::: -## Node Package Manager - -The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli). +#### Install the Polykey-CLI using this single command -# Step 1 - -Install it with: +To install the Polykey CLI globally on your system, execute the following command: ```sh npm install -g polykey-cli ``` -This will install the Polykey-CLI into `$(npm config get prefix)`. - -If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`. +**This command installs Polykey CLI globally, allowing you to access it with `pk` or `polykey` from any directory in your command line.** - + + +### Install Manually + + + + -## Linux +#### Linux Polykey-CLI code is compiled, bundled and wrapped into a single file executable. You just have to download the executable, give it executable permissions and run it. The executable is not statically linked. It requires a subset of the system libraries that Node.js requires. @@ -63,7 +60,7 @@ Polykey-CLI code is compiled, bundled and wrapped into a single file executable. - `libpthread.so.0` - `libc.so.6` -### Manually +##### Manually Builds for Linux is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases. @@ -75,9 +72,9 @@ Make it executable: chmod u+x ./polykey ``` -### Add it to your `$PATH`. +#### Add it to your `$PATH`. -#### For ZSH: +##### For ZSH: 1. `cd` into directory where polykey exec is stored. 2. Edit the zsh config to add polykey to your path, to streamline the process, run the following command making sure to change the path to polykey if the polykey executable is not in the downloads folder. @@ -97,7 +94,7 @@ You can now run it with `polykey`. --- -#### For Bash: +##### For Bash: 1. If you're using Bash, run the following command to add polykey to your path. Ensure to change the path if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems. @@ -115,7 +112,7 @@ You can now run it with `polykey`. --- -### NixOS +#### NixOS We have not yet published a Nixpkgs expression for Polykey. When we do, you will be able to just install `polykey-cli` from Nixpkgs. @@ -139,14 +136,14 @@ Build the application and install it into the user profile: nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" ``` -### Other +#### Other We will be working on other distribution methods. -## MacOS +#### MacOS :::info @@ -155,7 +152,7 @@ However, building Polykey yourself on MacOS resolves in a working binary. Follow ::: -### Manually +#### Manually 1. Download the Polykey CLI for macOS from the [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases). Look for the file named `polykey-cli-V.V.V-darwin-universal`, where `V.V.V` is the version number. For Mac, you want to download the file with the `darwin-universal` file extension. @@ -180,7 +177,7 @@ chmod +x polykey --- -### MacOS Security Bypass +#### MacOS Security Bypass MacOS requires additional steps for the binary to be allowed to execute, this is due to the fact that as of 20-12-23, the binaries we release are unsigned, @@ -189,7 +186,7 @@ and MacOS permits running of unsigned binaries, however, to progress past this, - #### Method #1 - quickest method +##### Method #1 - quickest method The xattr command will remove the quarantine attribute from the polykey executable, allowing you to run it without triggering macOS security warnings. Remember to ensure that the file path matches the location of your polykey file. @@ -206,7 +203,7 @@ If you have completed this sucesfully, you may ignore Method #2 and move to the -#### Method #2 - Using the Apple Systems Settings GUI +##### Method #2 - Using the Apple Systems Settings GUI First type the following command to try running the Polykey CLI but will instead trigger a pop-up. @@ -242,7 +239,7 @@ When prompted in the terminal, type your administrator password and hit enter. ![install3](/images/mac-install3.png) -#### Click on Open and now Polykey-CLI should be running in your terminal window. +##### Click on Open and now Polykey-CLI should be running in your terminal window. :::tip You can also verify the version of polykey that was installed with: @@ -258,14 +255,14 @@ You can also verify the version of polykey that was installed with: -### Add Polykey to your `$PATH`. +#### Add Polykey to your `$PATH`. To enable running the Polykey CLI from any directory in the terminal on macOS, you'll need to update your shell configuration file. -#### For ZSH (default shell on recent macOS versions): +##### For ZSH (default shell on recent macOS versions): 1. Navigate (cd) into the directory where the "polykey" executable is stored. @@ -284,7 +281,7 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc -#### For Bash: +##### For Bash: 1. `cd` into the directory where the "polykey" executable is stored. 2. Edit the Bash config to add "polykey" to your path. To streamline the process, run the following command, making sure to change the path to "polykey" if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems. @@ -324,9 +321,14 @@ Polykey for windows should be working but we have yet to create documentation on ::: - -## Docker + + + + + + +## Installing PK CLI on Docker The Docker image can be used so that Polykey can be deployed into the cloud. It is also possible to use the CLI via the docker container, but it isn't as convenient. The intention is to run the Polykey agent in the cloud. @@ -406,26 +408,47 @@ recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly ``` - - - + -## Source + -The official source repository is on GitHub. There is an additional mirror on GitLab. +## Setting Up Your First Node -```shell -git clone https://github.com/MatrixAI/Polykey-CLI.git -``` +When you run the `polykey agent start` for the first time after installing the CLI, it begins a bootstrapping process for you. +:::info +Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. +::: -Use `npm install` to setup the project. + -:::tip + -If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment. +### Starting the PK agent in the Foreground -::: + - + + +### Starting the PK agent in the Background + + + +Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. + + + +### Starting the Polykey Agent + +You can start the Polykey agent in the foreground of your terminal by running: + +```bash +polykey agent start +``` + +:::note +Running the agent in the foreground allows you to monitor its output directly in the terminal. Ensure this terminal session remains active to keep the agent running. You can execute Polykey commands from any other terminal session while this runs. +::: diff --git a/sidebars.ts b/sidebars.ts index c5bdf56d..59042ae6 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -10,7 +10,7 @@ const sidebars: SidebarsConfig = { { type: 'doc', id: 'README', // This should match the path to your symlink - label: 'Welcome to Polykey Docs', // Label for the sidebar item + label: 'Welcome to Polykey', // Label for the sidebar item }, 'getting-started/installing-polykey-cli', { From 79c666a6d785ea563ee2a4439a1a19b23274f2db Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Wed, 17 Jul 2024 14:39:15 +0100 Subject: [PATCH 09/23] WIP --- .../getting-started/installing-polykey-cli.md | 90 +++++++++++++------ images/pk-agent-start-bkg-bootstrap.png | 3 + images/pk-agent-status.png | 3 + images/pk-help.png | 3 + 4 files changed, 72 insertions(+), 27 deletions(-) create mode 100644 images/pk-agent-start-bkg-bootstrap.png create mode 100644 images/pk-agent-status.png create mode 100644 images/pk-help.png diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index 9f9d5b8a..fffb2351 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -4,7 +4,7 @@ import TabItem from '@theme/TabItem'; # Set-Up Polykey on your Machine :::note -The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. We designed the CLI user-experience (UX) to be suitable for a human operator, but also to be easily scripted and integrated into other tools. It is intended for developers and system administrators who require an advanced tool for managing secrets efficiently. +The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. It is designed to be human-operable and easily scriptable for integration into other tools. It targets developers and system administrators who need an advanced tool for efficient secrets management. ::: ## Choose Your Installation Method for the Polykey-CLI @@ -15,29 +15,29 @@ The Polykey Command Line Interface (CLI) is the primary user interface for the P ### Install using Node Package Manager -The Polykey CLI is available as an [`npm` package](https://www.npmjs.com/package/polykey-cli). This method allows for easy installation across various operating systems using Node.js and npm. +The Polykey CLI is available as an [`npm` package](https://www.npmjs.com/package/polykey-cli). This method facilitates easy installation across different operating systems using Node.js and npm. :::info #### System Requirements -Before installing, ensure your system meets the following requirements: +Before installing, ensure your system meets the following criteria: -- Node.js: Install the latest stable version of Node.js from nodejs.org -- npm (Node Package Manager): Comes with Node.js, but verify it’s updated by running `npm install -g npm` in your terminal. -- Environment Variables: Add the `npm` binary path to your system’s `$PATH` to run Polykey CLI from any terminal window. +- **Node.js**: Install the latest stable version from [nodejs.org](https://nodejs.org). +- **npm (Node Package Manager)**: Ensure it is up to date by running `npm install -g npm` in your terminal. +- **Environment Variables**: Add the `npm` binary path to your system’s `$PATH` to execute Polykey CLI commands from any terminal window. ::: -#### Install the Polykey-CLI using this single command +#### Install Command -To install the Polykey CLI globally on your system, execute the following command: +To install the Polykey CLI globally on your system, use the following command: ```sh npm install -g polykey-cli ``` -**This command installs Polykey CLI globally, allowing you to access it with `pk` or `polykey` from any directory in your command line.** +**Note**: This installs the Polykey CLI globally, allowing you to use `pk` or `polykey` commands from any directory. @@ -45,11 +45,13 @@ npm install -g polykey-cli ### Install Manually +Choose your operating system below to view specific installation instructions. + -#### Linux +#### Linux Installation Polykey-CLI code is compiled, bundled and wrapped into a single file executable. You just have to download the executable, give it executable permissions and run it. The executable is not statically linked. It requires a subset of the system libraries that Node.js requires. @@ -412,43 +414,77 @@ recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly -## Setting Up Your First Node +## Bootstrapping Your First Node -When you run the `polykey agent start` for the first time after installing the CLI, it begins a bootstrapping process for you. :::info Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. ::: - +### 1. Start the Polykey Agent - +```bash +polykey agent start --background +``` -### Starting the PK agent in the Foreground +:::info +When you run the `polykey agent start --background` for the first time after installing the CLI, it begins a bootstrapping process for you using a **default node path**. A default node is created for you when you run the polykey agent without specifying an argument for a custom node path. +::: - +### 2. Create & Confirm Your Password - +:::note -### Starting the PK agent in the Background +You'll be prompted to enter a **new password** for the default node on your machine. Once you confirm the new password, it will generate a node with a unique **nodeId** and **recoveryCode**. - +:::warning +Everytime you start the polykey agent for your default node, you'll be prompted to enter the password you created for that node so ensure you can remember it each time to access your node. +::: - +![pk-agent-start-bkg-bootstrap.png](/images/pk-agent-start-bkg-bootstrap.png) -Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. +
+Click here for a detailed explanation - +### 3. Verify the status of your PK agent -### Starting the Polykey Agent +:::info -You can start the Polykey agent in the foreground of your terminal by running: +This command provides detailed information about your node's current state, including its connectivity and activity within the network. ```bash -polykey agent start +polykey agent status ``` +![pk-agent-status.png](/images/pk-agent-status.png) + :::note -Running the agent in the foreground allows you to monitor its output directly in the terminal. Ensure this terminal session remains active to keep the agent running. You can execute Polykey commands from any other terminal session while this runs. + +If you made it this far, this means you sucesfully bootstrapped your first node on Polykey! + +::: + +### 4. Explore Polykey using the CLI's Helper + +```bash +polykey --help +``` + +![pk-help.png](/images/pk-help.png) + +### 5. Stopping the Polykey Agent + +You can stop the Polykey agent by running: + +```bash +polykey agent stop +``` + +:::info + +#### Troubleshooting + +If the Polykey agent does not terminate properly, you can force quit the process through the Activity Monitor on your machine. + ::: diff --git a/images/pk-agent-start-bkg-bootstrap.png b/images/pk-agent-start-bkg-bootstrap.png new file mode 100644 index 00000000..f7831a1c --- /dev/null +++ b/images/pk-agent-start-bkg-bootstrap.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9316b4698c38e4e769b445ff374b413f5e60ff1316305373f8e74e280dab2c0f +size 718234 diff --git a/images/pk-agent-status.png b/images/pk-agent-status.png new file mode 100644 index 00000000..e52a0405 --- /dev/null +++ b/images/pk-agent-status.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bbd69c54f8f810b9144a1d85f45ad6b0b7ee824742a214f740d012898ae99167 +size 116073 diff --git a/images/pk-help.png b/images/pk-help.png new file mode 100644 index 00000000..7cc55e69 --- /dev/null +++ b/images/pk-help.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f19eb33a63ada3294002c69220e5e19971374fa3af44ae1a13b348b1d085ce6d +size 654214 From 68cc3279a779b86f37f7a723bdb7fb6b757568a6 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 18 Jul 2024 14:08:34 +0100 Subject: [PATCH 10/23] docs: update getting started guide for setting up Polykey Improve the getting started section for setting up Polykey: - Updated instructions for installing PK-CLI. - Added detailed steps for bootstrapping the first node. - Included screenshots for better visual guidance. - Added inline notes, warnings, and tips to enhance user understanding. - Ensured consistent terminology and clear explanations throughout the guide. --- .../getting-started/installing-polykey-cli.md | 50 +++++++++++++------ 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index fffb2351..adc94bd2 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -37,7 +37,9 @@ To install the Polykey CLI globally on your system, use the following command: npm install -g polykey-cli ``` -**Note**: This installs the Polykey CLI globally, allowing you to use `pk` or `polykey` commands from any directory. +:::note +This installs the Polykey CLI globally, allowing you to use `pk` or `polykey` commands from any directory. +::: @@ -414,77 +416,95 @@ recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly +--- + ## Bootstrapping Your First Node -:::info -Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. +:::note +Bootstrapping is the process for setting up a new Polykey node. This involves generating a key pair, creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain. ::: ### 1. Start the Polykey Agent +To start the Polykey agent in the background, run the following command: + ```bash polykey agent start --background ``` :::info -When you run the `polykey agent start --background` for the first time after installing the CLI, it begins a bootstrapping process for you using a **default node path**. A default node is created for you when you run the polykey agent without specifying an argument for a custom node path. +Running `polykey agent start --background` for the first time initiates the bootstrapping process using a **default node path**. The Polykey agent creates a default node when no custom node path is specified. Meaning that simply running `polykey agent start` will always launch the pk agent for accessing the default node unless a node path argument is provided for accessing a different node. ::: ### 2. Create & Confirm Your Password :::note -You'll be prompted to enter a **new password** for the default node on your machine. Once you confirm the new password, it will generate a node with a unique **nodeId** and **recoveryCode**. +When prompted, create a **new password** for your default node. Confirm the password to generate a node with a unique **nodeId** and **recoveryCode**. :::warning -Everytime you start the polykey agent for your default node, you'll be prompted to enter the password you created for that node so ensure you can remember it each time to access your node. +You will need to enter this password every time you start the Polykey agent for your default node. Ensure you remember it to access your node. ::: ![pk-agent-start-bkg-bootstrap.png](/images/pk-agent-start-bkg-bootstrap.png)
Click here for a detailed explanation - +Detailed explanations about the bootstrapping process can be expanded here for users who want to understand more about the underlying mechanisms and security implications.
### 3. Verify the status of your PK agent -:::info - -This command provides detailed information about your node's current state, including its connectivity and activity within the network. +To check the status of your Polykey agent, run: ```bash polykey agent status ``` +:::info + +This command provides detailed information about your node's current state, including its **nodeId**, connectivity status, and any running processes. + ![pk-agent-status.png](/images/pk-agent-status.png) :::note -If you made it this far, this means you sucesfully bootstrapped your first node on Polykey! +If you have reached this step, you have successfully bootstrapped your first node on Polykey! ::: ### 4. Explore Polykey using the CLI's Helper +To explore the available primary commands and get more detailed help, use: + ```bash polykey --help ``` ![pk-help.png](/images/pk-help.png) +:::tip + +- Use polykey `[insert a primary command] --help` to list all sub-commands for a primary command. + +- Use polykey `[insert a primary command] [insert a sub-command] --help` for detailed information on specific sub-commands. + +::: + ### 5. Stopping the Polykey Agent -You can stop the Polykey agent by running: +To stop the Polykey agent, use: ```bash polykey agent stop ``` +### Troubleshooting + :::info -#### Troubleshooting +If you encounter issues with starting or stopping the Polykey agent, try the following: -If the Polykey agent does not terminate properly, you can force quit the process through the Activity Monitor on your machine. +- **Ensure the agent is not already running:** Use polykey agent status to check the current status. -::: +- **Force quit the agent:** If the agent does not terminate properly, use the Activity Monitor or equivalent process management tool on your operating system. From 68ae8a3dd5daf3abc0f1788ca660ce90327dbea1 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 18 Jul 2024 14:44:59 +0100 Subject: [PATCH 11/23] docs(sidebar): move gestalts CLI tutorials page to getting started container and update sidebar configuration --- .../{polykey-cli => }/claiming-digital-identities.md | 0 sidebars.ts | 3 ++- 2 files changed, 2 insertions(+), 1 deletion(-) rename docs/getting-started/{polykey-cli => }/claiming-digital-identities.md (100%) diff --git a/docs/getting-started/polykey-cli/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md similarity index 100% rename from docs/getting-started/polykey-cli/claiming-digital-identities.md rename to docs/getting-started/claiming-digital-identities.md diff --git a/sidebars.ts b/sidebars.ts index 59042ae6..7a06952d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -13,6 +13,8 @@ const sidebars: SidebarsConfig = { label: 'Welcome to Polykey', // Label for the sidebar item }, 'getting-started/installing-polykey-cli', + 'getting-started/claiming-digital-identities', + { type: 'category', label: 'Polykey CLI', @@ -24,7 +26,6 @@ const sidebars: SidebarsConfig = { 'getting-started/polykey-cli/bootstrapping', 'getting-started/polykey-cli/managing-vaults', 'getting-started/polykey-cli/managing-secrets', - 'getting-started/polykey-cli/claiming-digital-identities', 'getting-started/polykey-cli/discovering-other-users', 'getting-started/polykey-cli/sharing-vaults', 'getting-started/polykey-cli/managing-multiple-nodes', From 5e159a9a35d94b413f35db3823cc8e8632810061 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 18 Jul 2024 17:41:40 +0100 Subject: [PATCH 12/23] WIP --- .../claiming-digital-identities.md | 104 ++++++------------ 1 file changed, 32 insertions(+), 72 deletions(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index 655e2854..b513bcff 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -1,105 +1,65 @@ -# Claiming Digital Identities: Establishing Identity Linkages in Polykey +# Claiming Your Digital Identity -In Polykey, claiming a digital identity is a crucial step that allows users to establish their identity across various platforms and link these identities to their cryptographic keys. This process involves authenticating with external services, such as GitHub, and claiming ownership of an identity by posting a cryptographic link to a publicly verifiable location. +Welcome to Polykey, where securing your digital identity is seamless and secure. This guide walks you through linking your Polykey node with GitHub, enabling you to claim and authenticate your digital identity effortlessly. By posting a cryptographic link to a publicly verifiable location, you enhance security and simplify identity verification, making trust-building with others straightforward. -This tutorial will guide you through the steps to authenticate with GitHub and claim an identity using Polykey, enhancing security and streamlining identity verification, making it easier for other users to discover and trust your nodes. +Let's start by authenticating with GitHub, your gateway to claiming ownership of your digital identity in Polykey. -## Step 1: Authenticate with GitHub - -Authentication with a service provider like GitHub is the first step toward claiming your digital identity. This process allows Polykey to interact with GitHub on your behalf and access necessary information to claim your identity. - -![GitHub Authentication](/images/github-authentication.png) - -_This image provides a demo example of the GitHub authentication process._ - -### Command Usage +
+More Details -:::info +- **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. -```bash -polykey identities authenticate -``` +- **Security and Privacy Considerations**: Polykey adheres to high standards of security and privacy, using accessed data strictly for mentioned operations and not sharing it with third parties. For more details, refer to our [privacy policy](https://polykey.com/privacy-policy). +
-``: The identifier for the digital identity provider, such as "github". -::: +## Step 1: Authenticate with GitHub -:::note -Since Polykey currently only supports GitHub as an IdP, this is the command that you will use to start the authentication process. +Authentication with GitHub is the first step toward claiming your digital identity. This process allows Polykey to interact with GitHub on your behalf and access necessary information to claim your identity. ```bash -polykey identities authenticate github +polykey identities authenticate github.com ``` -::: - -This command begins the authentication process with GitHub. Follow the prompts in your terminal to complete the authentication, which may involve logging into your GitHub account and authorizing Polykey to access your GitHub information via a popup window. - :::tip -The code prompted by the browser will be displayed in your terminal as the user code. +Follow the prompts in your terminal to complete the authentication, which may involve logging into your GitHub account and authorizing Polykey to access your GitHub information via a popup window. ::: -### Lists all authenticated identities across all providers +![GitHub Authentication](/images/github-authentication.png) -`polykey identities authenticated` command will output the providerID and corresponding identityID of the authenticated IdP. This is a way to check that you completed the authentication process correctly. +
+How to Verify Your Authentication? -#### Example Usage +- **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. -```bash -polykey identities authenticated -``` +- **Security and Privacy Considerations**: Polykey adheres to high standards of security and privacy, using accessed data strictly for mentioned operations and not sharing it with third parties. For more details, refer to our [privacy policy](https://polykey.com/privacy-policy). +
-##### Example Output +## Step 2: Claim Your Identity + +After successfully authenticating with GitHub, claim your identity by posting a cryptographic link to a publicly verifiable location, such as a GitHub gist. This link serves as proof of ownership of the identity. ```bash -providerId github.com -identityId maverick +polykey identities claim github.com:my-gh-username ``` -### Technical Use of Permissions - -During the authentication process, here's what Polykey requests access to and why: - -- **Create Gists:** Polykey creates a gist under your GitHub account containing a cryptographic link. This link is a verifiable method that proves the ownership of your GitHub identity to anyone checking your Polykey gestalt graph. - -- **Read All User Profile Data:** This enables Polykey to access your profile details, including your username, followers, and public repository data. This information is used to ensure that the identity you claim corresponds accurately to your public digital footprint, enhancing trust and verification. - -- **Access User Email Addresses (read-only):** By accessing the email addresses associated with your account, Polykey can better manage notifications related to your secrets operations. - -#### Security and Privacy Considerations - -Polykey is committed to maintaining the highest standards of security and privacy. All data accessed is used strictly for the operations mentioned and is not shared with any third parties. Our privacy practices are designed to protect your information and ensure its confidentiality. For more details, please refer to our [privacy policy](https://polykey.com/privacy-policy). - -## Step 2: Claim Your Identity - -After successfully authenticating with GitHub, you can claim your identity. This involves posting a cryptographic link to a publicly verifiable location, such as a GitHub gist. This link serves as proof of ownership of the identity. +:::tip +Replace `my-gh-username` with your actual GitHub username. +::: Cryptolink -### Command Usage - -_This image provides a demo example of the cryptographic link that is generated._ - -:::info - -- ``: The specific identity identifier from the provider you authenticated with, which you will claim. - -- `polykey identities claim` argument for `` = `github.com`+ `:` + `GH username` +## Step 3: Verify Your Claim -::: +After claiming your identity, you have two primary methods to verify that your identity has been correctly claimed. -Replace `my-gh-username` with your actual GitHub username. This command claims your GitHub identity by posting a cryptographic link to a gist under your GitHub profile. +### Method 1: Check Your GitHub Gist -```bash -polykey identities claim github.com:my-gh-username -``` - -## Step 3: Verify Your Claim - -After claiming your identity, Polykey provides a link to a GitHub gist in your terminal. This is your primary method to verify that your identity has been correctly claimed. +Polykey provides a link to a GitHub gist in your terminal. This is one method to verify that your identity has been correctly claimed. ![Claim Id](/images/claim-id.png) - -_This image shows a demo example of the link to the gist that was created when claiming the identity which forms a gestalt._ +:::note +This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. +::: ### Primary Verification Method From 85a5603d84c8ae11c386bbc2ac9bc4fa5aa71876 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 18 Jul 2024 17:41:52 +0100 Subject: [PATCH 13/23] WIP --- .../getting-started/claiming-digital-identities.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index b513bcff..5f05a075 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -26,14 +26,6 @@ Follow the prompts in your terminal to complete the authentication, which may in ![GitHub Authentication](/images/github-authentication.png) -
-How to Verify Your Authentication? - -- **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. - -- **Security and Privacy Considerations**: Polykey adheres to high standards of security and privacy, using accessed data strictly for mentioned operations and not sharing it with third parties. For more details, refer to our [privacy policy](https://polykey.com/privacy-policy). -
- ## Step 2: Claim Your Identity After successfully authenticating with GitHub, claim your identity by posting a cryptographic link to a publicly verifiable location, such as a GitHub gist. This link serves as proof of ownership of the identity. @@ -50,11 +42,7 @@ Replace `my-gh-username` with your actual GitHub username. ## Step 3: Verify Your Claim -After claiming your identity, you have two primary methods to verify that your identity has been correctly claimed. - -### Method 1: Check Your GitHub Gist - -Polykey provides a link to a GitHub gist in your terminal. This is one method to verify that your identity has been correctly claimed. +After claiming your identity, polykey provides a link to a GitHub gist in your terminal. This is one method to verify that your identity has been correctly claimed. ![Claim Id](/images/claim-id.png) :::note From a24e3f729d0b554fda75e644d7a4ad195f8c7286 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Sun, 21 Jul 2024 20:38:16 +0100 Subject: [PATCH 14/23] WIP --- docs/getting-started/claiming-digital-identities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index 5f05a075..78ddd5fb 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -1,4 +1,4 @@ -# Claiming Your Digital Identity +# Claim Your Digital Identity Welcome to Polykey, where securing your digital identity is seamless and secure. This guide walks you through linking your Polykey node with GitHub, enabling you to claim and authenticate your digital identity effortlessly. By posting a cryptographic link to a publicly verifiable location, you enhance security and simplify identity verification, making trust-building with others straightforward. From b2c822970a455004f06ce5a9c8d0f3e4a444496b Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Sun, 21 Jul 2024 22:35:39 +0100 Subject: [PATCH 15/23] WIP --- .../claiming-digital-identities.md | 81 ++++++++++--------- 1 file changed, 44 insertions(+), 37 deletions(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index 78ddd5fb..803d74ee 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -1,11 +1,19 @@ # Claim Your Digital Identity -Welcome to Polykey, where securing your digital identity is seamless and secure. This guide walks you through linking your Polykey node with GitHub, enabling you to claim and authenticate your digital identity effortlessly. By posting a cryptographic link to a publicly verifiable location, you enhance security and simplify identity verification, making trust-building with others straightforward. +This guide helps you link your Polykey node to a GitHub identity, enhancing discoverability and trust within the network. -Let's start by authenticating with GitHub, your gateway to claiming ownership of your digital identity in Polykey. +
+Why Link a GitHub Identity? +Linking your node to GitHub allows other users to discover and interact with your node using a familiar and verifiable identity, simplifying trust-building across the network. +
+ +## Prerequisites + +- Ensure your Polykey node is installed and running. +- Have your GitHub login credentials ready.
-More Details +What data does Polykey manage from the authenticated IdP ? - **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. @@ -14,24 +22,26 @@ Let's start by authenticating with GitHub, your gateway to claiming ownership of ## Step 1: Authenticate with GitHub -Authentication with GitHub is the first step toward claiming your digital identity. This process allows Polykey to interact with GitHub on your behalf and access necessary information to claim your identity. +Authenticate your node with GitHub to allow Polykey to access necessary information for identity linking. ```bash polykey identities authenticate github.com ``` :::tip -Follow the prompts in your terminal to complete the authentication, which may involve logging into your GitHub account and authorizing Polykey to access your GitHub information via a popup window. + +Follow the prompts in your terminal, log into your GitHub account, and authorize the requested permissions. + ::: ![GitHub Authentication](/images/github-authentication.png) ## Step 2: Claim Your Identity -After successfully authenticating with GitHub, claim your identity by posting a cryptographic link to a publicly verifiable location, such as a GitHub gist. This link serves as proof of ownership of the identity. +Claim your GitHub identity to establish a verifiable link between your node and your GitHub account. ```bash -polykey identities claim github.com:my-gh-username +polykey identities claim github.com: ``` :::tip @@ -42,59 +52,56 @@ Replace `my-gh-username` with your actual GitHub username. ## Step 3: Verify Your Claim -After claiming your identity, polykey provides a link to a GitHub gist in your terminal. This is one method to verify that your identity has been correctly claimed. +Once claimed, you'll receive a link to a GitHub gist that verifies the identity link. ![Claim Id](/images/claim-id.png) :::note -This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. +Visit the provided gist URL to confirm the link's presence and validity. ::: -### Primary Verification Method - -Check your GH gists. Replace `my-github-username` with your actual gh username and navigate to the url. +## Understanding the Impact -```bash -https://gist.github.com/my-github-username -``` +Claiming a GitHub identity with your Polykey node creates a gestalt graph, enhancing your node's discoverability and trust within the network. -This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. Viewing this gist ensures your claim was successful and publicly verifiable. +![gestalts](/images/gestalts.png) -## Understanding Gestalt Graphs +
+Learn More About Gestalt Graphs -In Polykey, claiming identities creates a **gestalt graph**—a dynamic, interconnected network of your digital identities across various platforms. This graph facilitates the federated identity model, allowing for more robust and streamlined identity verification and management. +### Understanding Gestalt Graphs -![gestalts](/images/gestalts.png) +**Gestalt Graphs** are visual representations of the relationships and trust connections between different digital identities within Polykey. Each node on a graph symbolizes an identity or a claim, and the edges between nodes represent cryptographic verifications or trust relationships. -_This image shows a federated gestalt graph example concept map._ +#### How Gestalt Graphs Work -### How Gestalt Graphs Work +- **Nodes**: Represent individual identities linked to Polykey, such as a GitHub username. +- **Edges**: Signify the trust connections or verification links between various identities. -Each node within the graph represents an identity or a claim, and edges represent trust relationships or cryptographic verifications. As you claim more identities or add nodes, the graph expands, enhancing its utility by making identity verification straightforward and trust relationships more transparent. +As you expand your digital presence by claiming more identities, or by adding more nodes to your network, the gestalt graph grows accordingly. This dynamic expansion enhances the network's utility by streamlining the process of identity verification and making the establishment of trust relationships more transparent and traceable. -### Claiming Multiple Identities +#### Claiming Multiple Identities -Polykey enables you to manage your digital presence flexibly by supporting the claiming of multiple identities across different scenarios. Specifically, you can: +Polykey allows for flexible management of digital identities, accommodating multiple use cases: -- Link one node to several identity providers (IdPs), broadening your digital footprint and verification avenues as more IdPs are supported. +- **Multiple IdPs for a Single Node**: You can link one Polykey node to several identity providers, enhancing your digital verification pathways and security. +- **Single IdP Across Multiple Nodes**: Claim and link the same identity provider, like a GitHub username, across multiple Polykey nodes you control, thus broadening your digital identity and reach within the network. -- Claim the same identity provider, such as a GitHub username, across multiple unique nodes you control, consolidating your digital identity while expanding your network's reach. +#### Future Plans and IdP Support -### Future Plans and IdP Support +Currently, Polykey integrates with GitHub as a primary identity provider. Our ongoing development aims to broaden this integration to include various major identity providers (IdPs), significantly enhancing accessibility and user engagement. Future updates will also allow organizations to implement their own IdPs, offering even greater control and customization of identity management operations within Polykey. -Currently, Polykey supports GitHub as an identity provider (IdP). However, we are actively working to expand our support to include a wider range of major IdPs. This expansion will enhance Polykey's accessibility and versatility, accommodating a broader user base. Additionally, organizations will have the option to maintain their own IdPs, allowing for even greater customization and control over identity management within Polykey. +#### Benefits of Federated Identities -### Benefits of Federated Identities +Adopting a federated identity model through gestalt graphs provides several advantages: -Using a federated identity model through gestalt graphs offers several benefits: +- **Enhanced Security**: Links multiple identity proofs to fortify the authenticity and credibility of your digital identity. +- **Simplified Identity Management**: Manages multiple identities through a unified interface, reducing complexity and streamlining user interactions. +- **Interoperability**: Facilitates seamless interactions across different platforms and services, leveraging a cohesive identity framework. -- **Enhanced Security**: By linking various identity proofs, it strengthens the authenticity and credibility of your digital identity. -- **Simplified Management**: Manage multiple identities through a single interface, reducing complexity and improving user experience. -- **Interoperability:** Easily interact across different platforms and services using a unified identity framework. +Utilizing gestalt graphs within Polykey enhances operational security and simplifies digital identity management, making it an indispensable tool for users navigating complex digital environments. -Understanding and utilizing gestalt graphs in Polykey not only secures your operations but also significantly simplifies the process of digital identity management. +
## Conclusion -Claiming your digital identity in Polykey links your cryptographic operations to external accounts like GitHub, securing your operations and facilitating identity verification by others. This guide details the essential steps for authenticating, claiming, and verifying your identity in Polykey. - -In the next section, we will explore additional operations related to digital identity management in Polykey, including discovery of other users, trust management and permissions handling. +Successfully linking your Polykey node to your GitHub identity not only secures your digital interactions but also facilitates easier and more reliable verification by other network participants. From 9f883e3de4cab076e6b5040f2ff04889841c55f3 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Sun, 21 Jul 2024 22:39:30 +0100 Subject: [PATCH 16/23] WIP --- .../claiming-digital-identities.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index 803d74ee..adb4bac2 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -1,19 +1,19 @@ # Claim Your Digital Identity -This guide helps you link your Polykey node to a GitHub identity, enhancing discoverability and trust within the network. +This guide demonstrates how to link your Polykey node to a GitHub identity, enhancing discoverability and trust within the network.
Why Link a GitHub Identity? -Linking your node to GitHub allows other users to discover and interact with your node using a familiar and verifiable identity, simplifying trust-building across the network. +Linking your Polykey node to GitHub improves discoverability and simplifies trust-building within the network by providing a familiar and verifiable identity.
## Prerequisites -- Ensure your Polykey node is installed and running. -- Have your GitHub login credentials ready. +- Your default Polykey node must be installed and operational. +- Have access to your GitHub credentials.
-What data does Polykey manage from the authenticated IdP ? +Handled Data and Privacy - **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications. @@ -22,7 +22,7 @@ Linking your node to GitHub allows other users to discover and interact with you ## Step 1: Authenticate with GitHub -Authenticate your node with GitHub to allow Polykey to access necessary information for identity linking. +Initiate authentication with GitHub to allow your node to access necessary identity information. ```bash polykey identities authenticate github.com @@ -30,7 +30,7 @@ polykey identities authenticate github.com :::tip -Follow the prompts in your terminal, log into your GitHub account, and authorize the requested permissions. +Follow the terminal prompts to log into GitHub and authorize Polykey to access your information. ::: @@ -38,7 +38,7 @@ Follow the prompts in your terminal, log into your GitHub account, and authorize ## Step 2: Claim Your Identity -Claim your GitHub identity to establish a verifiable link between your node and your GitHub account. +Link your GitHub identity with your Polykey node to establish a verifiable identity connection. ```bash polykey identities claim github.com: @@ -52,16 +52,16 @@ Replace `my-gh-username` with your actual GitHub username. ## Step 3: Verify Your Claim -Once claimed, you'll receive a link to a GitHub gist that verifies the identity link. +Check the link to the GitHub gist provided by Polykey to verify your identity claim. ![Claim Id](/images/claim-id.png) :::note -Visit the provided gist URL to confirm the link's presence and validity. +Visit the gist URL to ensure it exists and is correct. ::: ## Understanding the Impact -Claiming a GitHub identity with your Polykey node creates a gestalt graph, enhancing your node's discoverability and trust within the network. +Claiming a GitHub identity creates a gestalt graph that enhances the discoverability of your node. ![gestalts](/images/gestalts.png) @@ -104,4 +104,4 @@ Utilizing gestalt graphs within Polykey enhances operational security and simpli ## Conclusion -Successfully linking your Polykey node to your GitHub identity not only secures your digital interactions but also facilitates easier and more reliable verification by other network participants. +Linking your GitHub identity with Polykey enhances both security and usability, making your digital interactions within the network more seamless and verifiable. From ed76e05ce71d9447c08138a9c9ad0616113f420a Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Wed, 24 Jul 2024 18:29:13 +0100 Subject: [PATCH 17/23] feat: added dark/light mode toggle --- docusaurus.config.ts | 13 ++--- src/css/custom-prism-theme.ts | 73 +++++++++++++++++++++++++++++ src/css/dark-custom-prism-theme.ts | 73 +++++++++++++++++++++++++++++ src/prism/custom-cli.js | 30 ++++++++++++ src/theme/prism-include-language.js | 26 ++++++++++ 5 files changed, 207 insertions(+), 8 deletions(-) create mode 100644 src/css/custom-prism-theme.ts create mode 100644 src/css/dark-custom-prism-theme.ts create mode 100644 src/prism/custom-cli.js create mode 100644 src/theme/prism-include-language.js diff --git a/docusaurus.config.ts b/docusaurus.config.ts index ae6fe883..089e673d 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -4,10 +4,6 @@ import type { Options as PluginGTagOptions } from '@docusaurus/plugin-google-gta import type { Options as ThemeOptions } from '@docusaurus/theme-classic'; import type { UserThemeConfig } from '@docusaurus/theme-common'; import { visit } from 'unist-util-visit'; -import { themes as prismThemes } from 'prism-react-renderer'; - -const lightCodeTheme = prismThemes.github; -const darkCodeTheme = prismThemes.dracula; /** * Docusaurus does not process JSX `` URLs @@ -65,7 +61,8 @@ const pluginTheme: [string, ThemeOptions] = [ const themeConfig: UserThemeConfig = { colorMode: { - disableSwitch: true, + defaultMode: 'dark', + // DisableSwitch: false, }, navbar: { logo: { @@ -213,9 +210,9 @@ const themeConfig: UserThemeConfig = { copyright: `Copyright © ${new Date().getFullYear()} Matrix AI`, }, prism: { - theme: lightCodeTheme, - darkTheme: darkCodeTheme, - additionalLanguages: ['shell-session'], + additionalLanguages: ['shell-session', 'bash'], + theme: require('./src/css/custom-prism-theme.ts'), + darkTheme: require('./src/css/dark-custom-prism-theme.ts'), }, }; diff --git a/src/css/custom-prism-theme.ts b/src/css/custom-prism-theme.ts new file mode 100644 index 00000000..10b1e51f --- /dev/null +++ b/src/css/custom-prism-theme.ts @@ -0,0 +1,73 @@ +import type { PrismTheme } from 'prism-react-renderer'; + +// To see changes in development restart docusaurus + +const theme: PrismTheme = { + plain: { + color: '#F8F8F2', + backgroundColor: '#282A36', + }, + styles: [ + { + types: ['prolog', 'constant', 'builtin'], + style: { + color: 'rgb(189, 147, 249)', + }, + }, + { + types: ['inserted', 'function'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['deleted'], + style: { + color: 'rgb(255, 85, 85)', + }, + }, + { + types: ['changed'], + style: { + color: 'rgb(255, 184, 108)', + }, + }, + { + types: ['punctuation', 'symbol'], + style: { + color: 'rgb(248, 248, 242)', + }, + }, + { + types: ['string', 'char', 'tag', 'selector'], + style: { + color: 'rgb(255, 121, 198)', + }, + }, + { + types: ['keyword', 'variable'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['command'], + style: { + color: 'rgb(167, 199, 231)', + }, + }, + { + types: ['comment'], + style: { + color: 'rgb(98, 114, 164)', + }, + }, + { + types: ['attr-name'], + style: { + color: 'rgb(241, 250, 140)', + }, + }, + ], +}; +export default theme; diff --git a/src/css/dark-custom-prism-theme.ts b/src/css/dark-custom-prism-theme.ts new file mode 100644 index 00000000..34727b4c --- /dev/null +++ b/src/css/dark-custom-prism-theme.ts @@ -0,0 +1,73 @@ +import type { PrismTheme } from 'prism-react-renderer'; + +// To see changes in development restart docusaurus + +const theme: PrismTheme = { + plain: { + color: '#F8F8F2', + backgroundColor: '#282A36', + }, + styles: [ + { + types: ['prolog', 'constant', 'builtin'], + style: { + color: 'rgb(189, 147, 249)', + }, + }, + { + types: ['inserted', 'function'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['deleted'], + style: { + color: 'rgb(255, 85, 85)', + }, + }, + { + types: ['changed'], + style: { + color: 'rgb(255, 184, 108)', + }, + }, + { + types: ['punctuation', 'symbol'], + style: { + color: 'rgb(248, 248, 242)', + }, + }, + { + types: ['string', 'char', 'tag', 'selector'], + style: { + color: 'rgb(255, 121, 198)', + }, + }, + { + types: ['keyword', 'variable'], + style: { + color: 'rgb(80, 250, 123)', + }, + }, + { + types: ['command'], + style: { + color: 'rgb(0, 199, 231)', + }, + }, + { + types: ['comment'], + style: { + color: 'rgb(98, 114, 164)', + }, + }, + { + types: ['attr-name'], + style: { + color: 'rgb(241, 250, 140)', + }, + }, + ], +}; +export default theme; diff --git a/src/prism/custom-cli.js b/src/prism/custom-cli.js new file mode 100644 index 00000000..71537937 --- /dev/null +++ b/src/prism/custom-cli.js @@ -0,0 +1,30 @@ +import { Prism } from 'prism-react-renderer'; + +Prism.languages.pkcli = { + comment: { + pattern: /#.*/, + greedy: true, + }, + keyword: + /\b(?:vaults|create|list|delete|log|rename|list|-h|secrets|get|update|stat)\b/, + command: { + pattern: /(^\s*|\s+)(polykey)(?=\s|$)/, + lookbehind: true, + }, + parameter: { + pattern: /--?\w+/, + alias: 'operator', + }, + string: { + pattern: /("|')(?:\\.|(?!\1)[^\\\r\n])*\1/, + greedy: true, + }, + function: { + pattern: /\b\w+(?=\()/, + alias: 'function', + }, + number: { + pattern: /\b\d+(?:\.\d+)?\b/, + alias: 'number', + }, +}; diff --git a/src/theme/prism-include-language.js b/src/theme/prism-include-language.js new file mode 100644 index 00000000..d293e534 --- /dev/null +++ b/src/theme/prism-include-language.js @@ -0,0 +1,26 @@ +import siteConfig from '@generated/docusaurus.config'; +export default function prismIncludeLanguages(prismObject) { + const { + themeConfig: { prism }, + } = siteConfig; + const { additionalLanguages } = prism; + // Prism components work on the Prism instance on the window, while prism- + // react-renderer uses its own Prism instance. We temporarily mount the + // instance onto window, import components to enhance it, then remove it to + // avoid polluting global namespace. + // You can mutate PrismObject: registering plugins, deleting languages... As + // long as you don't re-assign it + globalThis.Prism = prismObject; + additionalLanguages.forEach((lang) => { + if (lang === 'php') { + // eslint-disable-next-line global-require + require('prismjs/components/prism-markup-templating.js'); + } + + // eslint-disable-next-line global-require, import/no-dynamic-require + require(`prismjs/components/prism-${lang}`); + }); + require('@site/src/prism/custom-cli.js'); + + delete globalThis.Prism; +} From c4c81d0857418cfe196972fb4a186bd2d4e98359 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Wed, 24 Jul 2024 22:24:47 +0100 Subject: [PATCH 18/23] update: default light mode --- docusaurus.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 089e673d..c2803dfa 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -61,7 +61,7 @@ const pluginTheme: [string, ThemeOptions] = [ const themeConfig: UserThemeConfig = { colorMode: { - defaultMode: 'dark', + defaultMode: 'light', // DisableSwitch: false, }, navbar: { From 8017886d97aa0e770a5414571cc87cb1f98e0912 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Wed, 24 Jul 2024 22:42:32 +0100 Subject: [PATCH 19/23] update: change codeblock language from bash to pkcli to apply custom syntax highlighting --- docs/getting-started/claiming-digital-identities.md | 4 ++-- docs/getting-started/installing-polykey-cli.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/claiming-digital-identities.md b/docs/getting-started/claiming-digital-identities.md index adb4bac2..2412f66d 100644 --- a/docs/getting-started/claiming-digital-identities.md +++ b/docs/getting-started/claiming-digital-identities.md @@ -24,7 +24,7 @@ Linking your Polykey node to GitHub improves discoverability and simplifies trus Initiate authentication with GitHub to allow your node to access necessary identity information. -```bash +```pkcli polykey identities authenticate github.com ``` @@ -40,7 +40,7 @@ Follow the terminal prompts to log into GitHub and authorize Polykey to access y Link your GitHub identity with your Polykey node to establish a verifiable identity connection. -```bash +```pkcli polykey identities claim github.com: ``` diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index adc94bd2..a36210c2 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -428,7 +428,7 @@ Bootstrapping is the process for setting up a new Polykey node. This involves ge To start the Polykey agent in the background, run the following command: -```bash +```pkcli polykey agent start --background ``` @@ -457,7 +457,7 @@ Detailed explanations about the bootstrapping process can be expanded here for u To check the status of your Polykey agent, run: -```bash +```pkcli polykey agent status ``` @@ -477,7 +477,7 @@ If you have reached this step, you have successfully bootstrapped your first nod To explore the available primary commands and get more detailed help, use: -```bash +```pkcli polykey --help ``` @@ -495,7 +495,7 @@ polykey --help To stop the Polykey agent, use: -```bash +```pkcli polykey agent stop ``` From e860b11ffc29218d8209980f44537d5f6dd2079b Mon Sep 17 00:00:00 2001 From: Ihtsham Shafiq Date: Thu, 25 Jul 2024 11:55:34 +1000 Subject: [PATCH 20/23] fix: incorrect file name leading to syntax highlighting issues --- src/css/dark-custom-prism-theme.ts | 4 ++-- src/prism/custom-cli.js | 2 +- .../{prism-include-language.js => prism-include-languages.js} | 0 3 files changed, 3 insertions(+), 3 deletions(-) rename src/theme/{prism-include-language.js => prism-include-languages.js} (100%) diff --git a/src/css/dark-custom-prism-theme.ts b/src/css/dark-custom-prism-theme.ts index 34727b4c..bf2c78cb 100644 --- a/src/css/dark-custom-prism-theme.ts +++ b/src/css/dark-custom-prism-theme.ts @@ -2,7 +2,7 @@ import type { PrismTheme } from 'prism-react-renderer'; // To see changes in development restart docusaurus -const theme: PrismTheme = { +const darkTheme: PrismTheme = { plain: { color: '#F8F8F2', backgroundColor: '#282A36', @@ -70,4 +70,4 @@ const theme: PrismTheme = { }, ], }; -export default theme; +export default darkTheme; diff --git a/src/prism/custom-cli.js b/src/prism/custom-cli.js index 71537937..246f5cfc 100644 --- a/src/prism/custom-cli.js +++ b/src/prism/custom-cli.js @@ -6,7 +6,7 @@ Prism.languages.pkcli = { greedy: true, }, keyword: - /\b(?:vaults|create|list|delete|log|rename|list|-h|secrets|get|update|stat)\b/, + /\b(?:vaults|create|list|delete|log|rename|list|-h|secrets|get|update|agent|start|status|stop|identities|authenticate|stat)\b/, command: { pattern: /(^\s*|\s+)(polykey)(?=\s|$)/, lookbehind: true, diff --git a/src/theme/prism-include-language.js b/src/theme/prism-include-languages.js similarity index 100% rename from src/theme/prism-include-language.js rename to src/theme/prism-include-languages.js From c6c2f89029dcc9ea23008151fea9b8a01a31a184 Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 25 Jul 2024 19:15:02 +0100 Subject: [PATCH 21/23] docs: add note on starting the Polykey agent in foreground/background and explain --node-path usage --- .../getting-started/installing-polykey-cli.md | 50 ++++++++++++++++--- 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index a36210c2..281ddfe4 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -432,10 +432,53 @@ To start the Polykey agent in the background, run the following command: polykey agent start --background ``` +
+ Options for Starting the Polykey Agent + :::info -Running `polykey agent start --background` for the first time initiates the bootstrapping process using a **default node path**. The Polykey agent creates a default node when no custom node path is specified. Meaning that simply running `polykey agent start` will always launch the pk agent for accessing the default node unless a node path argument is provided for accessing a different node. + +#### Starting the polykey agent in the Foreground vs. the Background + +In this guide, we recommend starting the Polykey agent with the `--background` option because it allows the agent to run without occupying a terminal window, enabling you to use the shell for other commands. + +However, for monitoring network activity and debugging, running the Polykey agent in the foreground can be beneficial. To do this, execute the command without the `--background` option: + +```pkcli +polykey agent start +``` + +This will display real-time network connections and is particularly useful for observing the interactions between your node and seed nodes within the network. It also facilitates capturing error logs or unusual activity, which can be crucial for reporting issues. For verbose output, include the `--verbose` option: + +```pkcli +polykey agent start --verbose +``` + +#### Default Node Bootstrapping and the `--node-path` Option + +When you start the Polykey agent for the first time without specifying a node path, it automatically initializes using the default node path. This is convenient for quickly setting up a node: + +```pkcli +polykey agent start +``` + +If you wish to manage multiple nodes or specify a custom path for your node's data, you can use the `--node-path` option. This is necessary for targeting operations at a node located outside the default path. For example, to start an agent for a node in a custom directory, you would use: + +```pkcli +polykey bootstrap --node-path /custom/node/path +``` + +Then to start the Polykey agent for operating on the custom node, you would run: + +```pkcli +polykey agent start --node-path /custom/node/path +``` + +The same applies to any other Polykey commands that you wish to target the custom node. + ::: +
+ ### 2. Create & Confirm Your Password :::note @@ -448,11 +491,6 @@ You will need to enter this password every time you start the Polykey agent for ![pk-agent-start-bkg-bootstrap.png](/images/pk-agent-start-bkg-bootstrap.png) -
-Click here for a detailed explanation -Detailed explanations about the bootstrapping process can be expanded here for users who want to understand more about the underlying mechanisms and security implications. -
- ### 3. Verify the status of your PK agent To check the status of your Polykey agent, run: From afe7dbe797e62af707497cf881c93db850f586cd Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 25 Jul 2024 19:21:41 +0100 Subject: [PATCH 22/23] docs: improve CLI help command usage tips in user guide --- docs/getting-started/installing-polykey-cli.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index 281ddfe4..f720caf1 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -521,11 +521,21 @@ polykey --help ![pk-help.png](/images/pk-help.png) -:::tip +:::tip Use the CLI Helper Effectively + +- To list all sub-commands available for a primary command, type: + +```pkcli +polykey [primary command] --help +``` + +- For detailed information on a specific sub-command, type: -- Use polykey `[insert a primary command] --help` to list all sub-commands for a primary command. +```pkcli +polykey [primary command] [sub-command] --help +``` -- Use polykey `[insert a primary command] [insert a sub-command] --help` for detailed information on specific sub-commands. +These commands provide you with helpful guidance on using different functionalities within Polykey. ::: From fed1418cec4ade7f3a3bcaa6019199e9d9d6c01c Mon Sep 17 00:00:00 2001 From: CryptoTotalWar Date: Thu, 25 Jul 2024 20:38:36 +0100 Subject: [PATCH 23/23] docs: update troubleshooting guide for Polykey agent operations --- .../getting-started/installing-polykey-cli.md | 24 ++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/installing-polykey-cli.md b/docs/getting-started/installing-polykey-cli.md index f720caf1..62d1466b 100644 --- a/docs/getting-started/installing-polykey-cli.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -551,8 +551,26 @@ polykey agent stop :::info -If you encounter issues with starting or stopping the Polykey agent, try the following: +#### Issues with Starting the Polykey Agent: -- **Ensure the agent is not already running:** Use polykey agent status to check the current status. +- **Check for Existing Agent Instances:** Before starting a new agent, ensure there isn't already one running by executing: -- **Force quit the agent:** If the agent does not terminate properly, use the Activity Monitor or equivalent process management tool on your operating system. +```pkcli +polykey agent status +``` + +#### Issues with Stopping the Polykey Agent: + +- **Force Termination:** If the Polykey agent does not terminate properly, use Activity Monitor (macOS), Task Manager (Windows), or system monitor tools (Linux) to forcefully end the process. + +#### Errors on Agent Start: + +- **Seek Help:** If your Polykey agent fails to start due to an error, please reach out on our [Discord Server](https://discord.gg/vfXQZwwugc) and [submit a bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=) detailing the issue. + +To assist in diagnosing the issue, please include the verbose output from your terminal. Run the Polykey agent with the verbose flag: + +```pkcli +polykey agent start --verbose +``` + +:::