Skip to content

Commit 2a84351

Browse files
CryptoTotalWarCryptoTotalWar
authored
Merge pull request #39 from MatrixAI/feature-installation-updated
Feature installation updated - reviewed with @tegefaulkes
2 parents bc8341a + c6c9853 commit 2a84351

File tree

4 files changed

+298
-30
lines changed

4 files changed

+298
-30
lines changed

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ For this reason, we think of secrets as "capabilities".
5555

5656
All secrets put into vaults. Each vault is a persistent fully-encrypted virtual filesystem with automatic version history. Vaults can be shared with other Polykey agents.
5757

58-
Polykey's secrets management concept provides users with secure commuication and secure computation.
58+
Polykey's secrets management concept provides users with secure communication and secure computation.
5959

6060
### Decentralized Trust
6161

‎docs/tutorials/polykey-cli/installation.md‎

Lines changed: 291 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,29 @@
1+
import Tabs from '@theme/Tabs';
2+
import TabItem from '@theme/TabItem';
3+
14
# Installation
25

36
Installing the CLI can be done in different ways depending on your operating environment.
47

5-
:::warning
8+
:::info
69

7-
Polykey-CLI has only been tested on Linux. We are working on supporting other platforms. There's minor teething problems when it comes supporting other platforms. Help us by reporting issues.
10+
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).
811

912
:::
1013

14+
<Tabs>
15+
<TabItem value="linux" label="Linux" default>
16+
1117
## Linux
1218

1319
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.
1420

15-
* `libdl.so.2`
16-
* `libstdc++.so.6`
17-
* `libm.so.6`
18-
* `libgcc_s.so.1`
19-
* `libpthread.so.0`
20-
* `libc.so.6`
21+
- `libdl.so.2`
22+
- `libstdc++.so.6`
23+
- `libm.so.6`
24+
- `libgcc_s.so.1`
25+
- `libpthread.so.0`
26+
- `libc.so.6`
2127

2228
### Manually
2329

@@ -31,11 +37,45 @@ Make it executable:
3137
chmod u+x ./polykey
3238
```
3339

34-
Add it to your `$PATH`.
40+
### Add it to your `$PATH`.
41+
42+
#### For ZSH:
43+
44+
1. `cd` into directory where polykey exec is stored.
45+
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.
46+
3. For most users, this would be `~/downloads` on Debian based systems.
47+
48+
:::warning
49+
50+
Make sure your path to the polykey executable is correct.
51+
52+
:::
53+
54+
```SH
55+
echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc
56+
```
3557

3658
You can now run it with `polykey`.
3759

38-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
60+
---
61+
62+
#### For Bash:
63+
64+
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.
65+
66+
:::warning
67+
68+
Make sure your path to the polykey executable is correct.
69+
70+
:::
71+
72+
```sh
73+
echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc
74+
```
75+
76+
You can now run it with `polykey`.
77+
78+
---
3979

4080
### NixOS
4181

@@ -65,39 +105,189 @@ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(pr
65105

66106
We will be working on other distribution methods.
67107

108+
</TabItem>
109+
<TabItem value="macos" label="MacOs">
110+
68111
## MacOS
69112

70-
Polykey-CLI code is compiled, bundled and wrapped into a single file executable. However modern MacOS has made it significantly difficult to run arbitrary executables on their operating system. Additionally MacOS can be in both Intel or ARM64 CPU architectures. As of now, Polykey distributes Mach-O executables for both architectures. However the user will need to allow the executable to run on their system.
113+
:::info
71114

72-
The following links may help:
115+
ARM-64 builds are not currently supported on MacOS as of **26-03-24.**
116+
However, building Polykey yourself on MacOS resolves in a working binary. Follow this guide below to manually build and install Polykey on macOS.
73117

74-
* https://openecoacoustics.org/resources/help-centre/software/unsigned/
75-
* https://github.molgen.mpg.de/pages/bs/macOSnotes/mac/mac_procs_unsigned.html
76-
* https://github.com/MatrixAI/TypeScript-Demo-Lib/pull/38#issuecomment-1131228064
118+
:::
77119

78-
We have plans to distribute automatically signed binaries in the future which will make it easier to just download and run. However CLI programs will never distributed through the Mac App store. Mac users may prefer Polykey-Desktop which will be distributed through the Mac App Store.
120+
### Manually
79121

80-
Builds for MacOS is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
122+
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.
81123

82-
Download the executable named `...-polykey-cli-V.V.V-macos-x64`, and rename it to `polykey`.
124+
2. Rename the downloaded file to `polykey` for easier access. In your terminal, make sure to navigate to the directory where the file is located (usually the Downloads directory) and run the following command:
83125

84-
You can now run it with `polykey`.
126+
```sh
127+
mv polykey-cli-V.V.V-darwin-universal polykey
128+
```
85129

86-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
130+
:::tip
87131

88-
## Windows
132+
- Navigate into the directory where the file is saved to execute commands.
133+
- Replace `V.V.V.` with the actual version number of the file you downloaded.
89134

90-
Polykey-CLI code is compiled, bundled and wrapped into a single file executable.
135+
:::
91136

92-
Builds for Linux is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
137+
3. Make the Executable Runnable: Before you can run the Polykey CLI, you need to make it executable. Use the `chmod +x` command to add executable permissions to the file. Replace `polykey` with the actual name of your file if it's different:
93138

94-
Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it to `polykey`.
139+
```sh
140+
chmod +x polykey
141+
```
95142

96-
You can now run it with `polykey`.
143+
---
144+
145+
### MacOS Security Bypass
146+
147+
MacOS requires additional steps for the binary to be allowed to execute,
148+
this is due to the fact that as of 20-12-23, the binaries we release are unsigned,
149+
and MacOS permits running of unsigned binaries, however, to progress past this, there are a couple options:
150+
151+
<Tabs>
152+
<TabItem value="method1" label="Method #1 - Admin CLI ">
153+
154+
#### Method #1 - quickest method
155+
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.
156+
157+
```sh
158+
sudo xattr -r -d com.apple.quarantine ~/Downloads/polykey
159+
```
160+
161+
If you have completed this sucesfully, you may ignore Method #2 and move to the next section on how to add polykey to your `$PATH`.
162+
163+
## <!-- I need to add a link to skip ahead -->
164+
165+
---
166+
167+
</TabItem>
168+
<TabItem value="method2" label="Method #2 - Apple Setting GUI">
169+
170+
#### Method #2 - Using the Apple Systems Settings GUI
171+
172+
First type the following command to try running the Polykey CLI but will instead trigger a pop-up.
173+
174+
```sh
175+
./polykey --version
176+
```
177+
178+
1. MacOS will then prompt you with the following:
179+
180+
:::important
181+
Do not close this prompt. If you do, the 'Allow Anyway' option will not appear in the next step.
182+
:::
183+
184+
![install1](../../../images/mac-install1.png)
185+
186+
2. While keeping the prompt open, head over to `Settings -> Privacy & Security` and scroll down till you see '"polykey" was blocked from use because it is not from an identified developer.'
187+
188+
![install2](../../../images/mac-install2.png)
189+
190+
3. Click on `Allow Anyway` and authenticate.
191+
192+
4. Try opening polykey with
193+
194+
```shell
195+
sudo ./polykey
196+
```
197+
198+
:::tip
199+
When prompted in the terminal, type your administrator password and hit enter.
200+
:::
201+
202+
5. Following this, you will get another similar prompt
203+
204+
![install3](../../../images/mac-install3.png)
205+
206+
#### Click on Open and now Polykey-CLI should be running in your terminal window.
207+
208+
:::tip
209+
You can also verify the version of polykey that was installed with:
210+
211+
```sh
212+
./polykey --version
213+
```
214+
215+
:::
216+
217+
---
97218

98-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
219+
</TabItem>
220+
</Tabs>
99221

100-
## Docker
222+
### Add Polykey to your `$PATH`.
223+
224+
To enable running the Polykey CLI from any directory in the terminal on macOS, you'll need to update your shell configuration file.
225+
226+
<Tabs>
227+
<TabItem value="zsh" label="ZSH (default shell on recent macOS versions)">
228+
229+
#### For ZSH (default shell on recent macOS versions):
230+
231+
1. Navigate (cd) into the directory where the "polykey" executable is stored.
232+
233+
2. Edit the Zsh configuration file to add "polykey" to your $PATH. Use the following command, ensuring to replace ~/Downloads with the correct path to the "polykey" executable if it's not in the downloads folder. For most users, this path would be ~/Downloads on Debian-based systems.
234+
235+
:::tip
236+
237+
Make sure your path to the "polykey" executable is correct.
238+
239+
:::
240+
241+
```sh
242+
echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc
243+
```
244+
245+
</TabItem>
246+
<TabItem value="bash" label="Bash">
247+
248+
#### For Bash:
249+
250+
1. `cd` into the directory where the "polykey" executable is stored.
251+
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.
252+
253+
:::tip
254+
255+
Make sure your path to the "polykey" executable is correct. Replace `downloads` with the path to the working directory
256+
257+
:::
258+
259+
```sh
260+
echo 'export PATH=~/downloads:$PATH' >> ~/.bashrc && source ~/.bashrc
261+
```
262+
263+
</TabItem>
264+
</Tabs>
265+
266+
:::tip
267+
268+
You can check if the PATH environment variable for Polykey has been updated correctly by running:
269+
270+
```sh
271+
polykey --version
272+
```
273+
274+
If this command returns the current version, then you have successfully added Polykey to your PATH, and you can now run polykey from anywhere in your terminal.
275+
276+
:::
277+
278+
</TabItem>
279+
<TabItem value="windows" label="Windows">
280+
281+
:::warning
282+
283+
Polykey for windows should be working but we have yet to create documentation on the installation process for this.
284+
285+
:::
286+
287+
</TabItem>
288+
<TabItem value="docker" label="Docker">
289+
290+
## Docker
101291

102292
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.
103293

@@ -113,6 +303,73 @@ image="$(cut -d' ' -f3 <<< "$loaded")"
113303
docker run -it "$image"
114304
```
115305

306+
### Docker for Mac
307+
308+
:::tip
309+
310+
You can install nix for MacOS and then follow the general docker instructions above.
311+
Nix for mac can be installed by running
312+
313+
```sh
314+
sh <(curl -L https://nixos.org/nix/install)
315+
```
316+
317+
:::
318+
319+
1. Download the latest build of Polykey-CLI for docker from https://polykey.com/download.
320+
321+
2. Download Docker for MacOS depending on your instruction-set (arm vs x86) from https://docs.docker.com/desktop/install/mac-install/
322+
323+
3. Rename the Polykey dist from `x-docker-image-polykey-cli-x.x.x-alpha.x.tar.gz` to `docker-polykey.tar.gz`
324+
325+
4. Load the image in docker using the following:
326+
327+
```shell
328+
docker load --input docker-polykey.tar.gz
329+
```
330+
331+
5. Go to your docker application and configure the Polykey image
332+
333+
![img.png](../../../images/docker-mac-img1.png)
334+
335+
6. Run `mkdir /tmp/polykey` to create a directory for the polykey nodepath
336+
337+
7. Set the volume host path to `/tmp/polykey` and the container path to `/tmp/polykey/`
338+
339+
8. Run `docker images` to grab the Image ID of your installed image.
340+
341+
```shell
342+
> docker images
343+
REPOSITORY TAG IMAGE ID CREATED SIZE
344+
polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 days ago 370MB
345+
```
346+
347+
9. Now you can run Polykey as an agent with the following shell command
348+
349+
```shell
350+
docker run -it 0e1addd9855a agent start --background -np /tmp/polykey
351+
```
352+
353+
Making sure to replace `0e1addd9855a` with your corresponding image ID.
354+
355+
```shell
356+
 docker run -it 0e1addd9855a agent start --background -np /tmp/polykey
357+
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
358+
✔ Enter new password … *
359+
✔ Confirm new password … *
360+
pid 28
361+
nodeId vflhiouqt255gq22drpf0s639kl9eds3ralu094c6rsnmonemp6pg
362+
clientHost 127.0.0.1
363+
clientPort 45509
364+
agentHost ::
365+
agentPort 37468
366+
recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw
367+
368+
```
369+
370+
</TabItem>
371+
<TabItem value="npm" label="npm">
372+
116373
## Node Package Manager
117374
118375
The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli).
@@ -127,6 +384,9 @@ This will install the Polykey-CLI into `$(npm config get prefix)`.
127384
128385
If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`.
129386
387+
</TabItem>
388+
<TabItem value="source" label="Source">
389+
130390
## Source
131391
132392
The official source repository is on GitHub. There is an additional mirror on GitLab.
@@ -142,3 +402,7 @@ Use `npm install` to setup the project.
142402
If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment.
143403
144404
:::
405+
406+
</TabItem>
407+
408+
</Tabs>

0 commit comments

Comments
 (0)