diff --git a/docs/README.md b/docs/README.md index f2163de..375d8da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,16 +5,25 @@ displayed_sidebar: docs # Polykey Documentation -Welcome to the Polykey documentation. + -- [Tutorials](./tutorials) - 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/tutorials/polykey-cli/installation.md b/docs/getting-started/installing-polykey-cli.md similarity index 73% rename from docs/tutorials/polykey-cli/installation.md rename to docs/getting-started/installing-polykey-cli.md index f477832..9f9d5b8 100644 --- a/docs/tutorials/polykey-cli/installation.md +++ b/docs/getting-started/installing-polykey-cli.md @@ -1,20 +1,55 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Installation +# Set-Up Polykey on your Machine -Installing the CLI can be done in different ways depending on your operating environment. +:::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 + + + + + +### 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 -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). +#### System Requirements + +Before installing, ensure your system meets the following requirements: + +- 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. ::: +#### Install the Polykey-CLI using this single command + +To install the Polykey CLI globally on your system, execute 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.** + + + + + +### 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. @@ -25,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. @@ -37,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. @@ -59,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. @@ -77,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. @@ -101,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 @@ -117,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. @@ -142,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, @@ -151,7 +186,8 @@ 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. ```sh @@ -167,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. @@ -203,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: @@ -219,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. @@ -245,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. @@ -285,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. @@ -367,42 +408,47 @@ 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). +## Setting Up Your First Node -Install it with: +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. +::: -```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`. +### Starting the PK agent in the Foreground - - + -## Source + -The official source repository is on GitHub. There is an additional mirror on GitLab. +### Starting the PK agent in the Background -```shell -git clone https://github.com/MatrixAI/Polykey-CLI.git -``` + -Use `npm install` to setup the project. + -:::tip +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. -If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment. + - +### 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/docs/tutorials/polykey-cli/README.md b/docs/getting-started/polykey-cli/README.md similarity index 64% rename from docs/tutorials/polykey-cli/README.md rename to docs/getting-started/polykey-cli/README.md index c254b95..43fb16a 100644 --- a/docs/tutorials/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: 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/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/reference/polykey-desktop/README.md b/docs/reference/polykey-desktop/README.md deleted file mode 100644 index c32c68e..0000000 --- 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 cd37bc9..0000000 --- a/docs/reference/polykey-mobile/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey-Mobile - - diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md deleted file mode 100644 index 7077183..0000000 --- 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/docs/tutorials/polykey-desktop/README.md b/docs/tutorials/polykey-desktop/README.md deleted file mode 100644 index af7d379..0000000 --- a/docs/tutorials/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/tutorials/polykey-mobile/README.md b/docs/tutorials/polykey-mobile/README.md deleted file mode 100644 index 698807c..0000000 --- a/docs/tutorials/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/sidebars.ts b/sidebars.ts index 7b25180..59042ae 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,58 +4,41 @@ const sidebars: SidebarsConfig = { docs: [ { type: 'category', - label: 'Tutorials', + label: 'Getting Started', collapsed: false, - link: { - type: 'doc', - id: 'tutorials/README', - }, items: [ + { + type: 'doc', + id: 'README', // This should match the path to your symlink + label: 'Welcome to Polykey', // Label for the sidebar item + }, + 'getting-started/installing-polykey-cli', { type: 'category', label: 'Polykey CLI', link: { type: 'doc', - id: 'tutorials/polykey-cli/README', + id: 'getting-started/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', + '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: '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', + id: 'getting-started/polykey-core/README', }, - items: ['tutorials/polykey-core/installation'], + items: ['getting-started/polykey-core/installation'], }, ], }, @@ -152,24 +135,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',