Skip to content

Commit f6c784a

Browse files
xrissoulaxrissoula
committed
feat: New Landing Page and Sidebars, Documents Updates
1 parent e1d2058 commit f6c784a

14 files changed

Lines changed: 2258 additions & 13 deletions

‎docs/Getting-Started/polykey-cli/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import DocCardList from '@theme/DocCardList';
2+
3+
# Polykey CLI
4+
5+
The Polykey Command Line Interface (CLI) is the primary user interface for the
6+
Polykey system, tailored for developers and system administrators. It was
7+
conceived from the necessity of managing secrets efficiently during software
8+
development and deployment workflows.
9+
10+
## Overview
11+
12+
The Polykey CLI is the first and primary interface to the Polykey system. It is
13+
intended for developers and system administrators who require an advanced tool
14+
for managing secrets efficiently. New features are introduced in the CLI first,
15+
serving as a testing and integration ground before being ported to other user
16+
interfaces. This approach ensures that the features are reliable and refined for
17+
professional use.
18+
19+
We designed the CLI user-experience (UX) to be suitable for a human operator,
20+
but also to be easily scripted and integrated into other tools.
21+
22+
The tutorial here should be followed in order, and the goal is to make use of
23+
Polykey to manage secrets for a simple application from development to
24+
deployment.
25+
26+
The CLI is open-source and available on GitHub:
27+
[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI).
28+
29+
### Supported Platforms
30+
31+
Polykey is continuously built and tested on:
32+
33+
- Linux x64 / arm64
34+
- MacOS x64 / arm64
35+
- Windows x64
36+
- Docker
37+
38+
:::note Polykey is currently in beta. Its interface is at various levels of
39+
stability. So bear with us as we perfect its design. You can contribute by
40+
discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue
41+
tickets in the
42+
[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). :::
43+
44+
## Getting Started
45+
46+
Start your journey with Polykey by following the tutorials below in sequence:
47+
48+
:::tip For a visual walkthrough, check out our
49+
[getting started demo video](https://vimeo.com/884649667) after installing
50+
Polykey. :::
51+
52+
1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install
53+
Polykey CLI on your platform.
54+
2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)** - Set up
55+
your node and connect to the network.
56+
3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)** - Securely
57+
store secrets within encrypted vaults.
58+
4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)** -
59+
Organize and handle secrets within your vaults.
60+
5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)** -
61+
Establish and authenticate your identity within the network.
62+
6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)** -
63+
Find and verify other users to manage permissions.
64+
7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)** - Share your
65+
encrypted vaults securely with peers.
66+
8. **[Managing Multiple Nodes](/docs/tutorials/polykey-cli/managing-multiple-nodes)** -
67+
Operate multiple local nodes/agents.
68+
9. **[Using Environment Variables](/docs/tutorials/polykey-cli/using-environment-variables)** -
69+
Master `polykey secrets env` for dynamic environment management.
70+
71+
Explore advanced scenarios in subsequent sections, including:
72+
73+
- Managing multiple local nodes
74+
- Integrating multiple nodes with a single identity
75+
- Injecting secrets directly into your development environments using Polykey’s
76+
`env` command
77+
78+
This will prepare you to fully exploit Polykey’s capabilities in diverse and
79+
complex operational settings.
80+
81+
<DocCardList />

‎docs/Getting-Started/polykey-cli/bootstrapping.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Bootstrapping
2+
3+
## Introduction
4+
5+
Bootstrapping is the process where the Polykey agent sets itself up as a new
6+
Polykey node. This involves creating the encrypted-at-rest node state, and
7+
connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified
8+
network domain.
9+
10+
## Setting Up Your Node
11+
12+
### Creating the Root Key
13+
14+
When you first start the Polykey agent, it automatically generates a random root
15+
key.
16+
17+
This root key is an asymmetric key pair consisting of a public key representing
18+
your identity and used for verifying signatures, and a private key which is used
19+
for signing.
20+
21+
Afterwards, encryption keys are derived from this root key, which is used for
22+
encryption and decryption of all node state and secret data managed by Polykey.
23+
24+
You will be prompted to provide a root password. This password encrypts the root
25+
key.
26+
27+
:::note Remember to keep your password in a secure location as you will need it
28+
each time you start the Polykey agent. :::
29+
30+
### Starting the Polykey Agent
31+
32+
You can start the Polykey agent in the foreground of your terminal by running:
33+
34+
```bash
35+
polykey agent start --verbose
36+
```
37+
38+
Running the agent in the foreground allows you to monitor its output directly in
39+
the terminal. Ensure this terminal session remains active to keep the agent
40+
running. You can execute Polykey commands from any other terminal session while
41+
this runs.
42+
43+
### Starting Polykey in the Background
44+
45+
Alternatively, in the demo video and other scenarios where you do not wish to
46+
occupy your terminal, you can start the agent in the background:
47+
48+
```bash
49+
polykey agent start --verbose --background
50+
```
51+
52+
### Stopping the Polykey Agent
53+
54+
You can stop the Polykey agent by pressing **Control+C** in the terminal where
55+
it's running in the foreground, or by running:
56+
57+
```bash
58+
polykey agent stop
59+
```
60+
61+
#### Troubleshooting
62+
63+
If the Polykey agent does not terminate properly, you can force quit the process
64+
through the Activity Monitor on your machine. If you encounter this or any other
65+
issue, please consider making a
66+
[bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help
67+
improve Polykey.
68+
69+
## Check Agent Status
70+
71+
To check the status of your Polykey node, use the following command:
72+
73+
```bash
74+
polykey agent status
75+
```
76+
77+
This command provides detailed information about your node's current state,
78+
including its connectivity and activity within the network.
79+
80+
### Example Output
81+
82+
```bash
83+
status LIVE
84+
pid 96992
85+
nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg
86+
clientHost ::1
87+
clientPort 54975
88+
agentHost ::
89+
agentPort 60358
90+
upTime 8
91+
startTime 1716509093
92+
connectionsActive 3
93+
nodesTotal 11
94+
version 1.2.3-alpha.4-1-1
95+
sourceVersion 1.2.3-alpha.4
96+
stateVersion 1
97+
networkVersion 1
98+
```
99+
100+
## Check Network Status
101+
102+
When your agent has started, it should show as a node on the network. By default
103+
the network is [mainnet](https://mainnet.polykey.com/). Check out the network
104+
dashboard to see your placement on the world map.
105+
106+
## Monitoring Network Connections
107+
108+
To view the nodes currently connected to the network, including the seed nodes,
109+
run:
110+
111+
```bash
112+
polykey nodes connections
113+
```
114+
115+
This will list all active connections, including details about each node.
116+
117+
### Example Output
118+
119+
```bash
120+
host hostname nodeIdEncoded port timeout usageCount
121+
3.145.86.40 N/A v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0 1314 46873 0
122+
13.239.117.143 N/A vncm2mkk41vgp2fmplqiu1je7b2l3v6fhgltlqf5f3f85923ve0j0 1314 116186 0
123+
1.145.55.96 N/A vg6gldhfdstju8frtbguav2p2svmev85dvpdb34gffmiagpgjf2pg 1200 102086 0
124+
```
125+
126+
## Checking Node Activity
127+
128+
To determine if a specific node is active, use the ping command:
129+
130+
```bash
131+
polykey nodes ping <nodeID>
132+
```
133+
134+
This will tell you whether the node is active within the network.
135+
136+
### Example Output
137+
138+
```bash
139+
polykey nodes ping v6p14qcvvftnnscuavsehu37t22vfvnhse054pbkb3ehemmjsrdh0
140+
Node is Active
141+
```
142+
143+
## Conclusion
144+
145+
Bootstrapping your node is the first step to using Polykey effectively. It
146+
prepares your node for managing and sharing secrets securely within the network.
147+
By following these guidelines, you ensure that your node is well-configured,
148+
secure, and ready for advanced operations in the Polykey ecosystem.
149+
150+
Stay tuned for upcoming sections where we will discuss managing multiple nodes,
151+
assigning different file paths to each node, and other advanced configurations.

0 commit comments

Comments
 (0)