Skip to content

Commit 92dd4da

Browse files
CryptoTotalWartegefaulkes
CryptoTotalWar
authored and
tegefaulkes
committed
chore: pulled changes to installation.md from reference cli commands and reference docs and ECIES & installation instructions 
1 parent bc8341a commit 92dd4da

File tree

1 file changed

+204
-16
lines changed

1 file changed

+204
-16
lines changed

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

Lines changed: 204 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,44 @@ Make it executable:
3131
chmod u+x ./polykey
3232
```
3333

34-
Add it to your `$PATH`.
34+
### Add it to your `$PATH`.
35+
36+
#### For ZSH:
37+
38+
1. `cd` into directory where polykey exec is stored.
39+
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.
40+
3. For most users, this would be ``~/downloads`` on Debian based systems.
41+
42+
:::warning
43+
44+
Make sure your path to the polykey executable is correct.
45+
46+
:::
47+
48+
```SH
49+
echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc
50+
```
51+
52+
You can now run it with `polykey`.
53+
54+
---
55+
#### For Bash:
56+
57+
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.
58+
59+
:::warning
60+
61+
Make sure your path to the polykey executable is correct.
62+
63+
:::
64+
65+
```sh
66+
echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc
67+
```
3568

3669
You can now run it with `polykey`.
3770

38-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
71+
---
3972

4073
### NixOS
4174

@@ -67,35 +100,125 @@ We will be working on other distribution methods.
67100

68101
## MacOS
69102

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.
103+
:::info
104+
105+
ARM-64 builds don't work on MacOS as of **20-12-23.**
106+
However, building polykey yourself on MacOS resolves in a working binary.
107+
108+
:::
109+
110+
111+
Builds for MacOS are released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
112+
113+
Download the executable named `...-polykey-cli-V.V.V-darwin-x64`, and rename it to `polykey`.
114+
115+
116+
:::tip
117+
118+
Make sure to cd into the right directory first.
119+
120+
:::
121+
122+
Make it executable:
123+
124+
```sh
125+
chmod +x polykey
126+
```
127+
128+
MacOS requires additional steps for the binary to be allowed to execute,
129+
this is due to the fact that as of 20-12-23, the binaries we release are unsigned,
130+
and MacOS permits running of unsigned binaries, however, to progress past this, follow these steps:
131+
132+
1. MacOS will prompt you with the following:
133+
134+
![install1](../../../images/mac-install1.png)
135+
136+
2. 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.'
137+
138+
![install2](../../../images/mac-install2.png)
139+
140+
3. Click on `Allow Anyway` and authenticate.
141+
142+
4. Try opening polykey with
71143

72-
The following links may help:
144+
```shell
145+
sudo ./polykey
146+
```
147+
5. Following this, you will get another similar prompt
148+
149+
![install3](../../../images/mac-install3.png)
150+
151+
#### Click on Open and now Polykey-CLI should be running in your terminal window.
73152

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
153+
### Add it to your `$PATH`.
77154

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.
155+
#### For ZSH:
79156

80-
Builds for MacOS is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
157+
1. `cd` into the directory where the "polykey" executable is stored.
158+
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 executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems.
81159

82-
Download the executable named `...-polykey-cli-V.V.V-macos-x64`, and rename it to `polykey`.
160+
:::tip
161+
162+
Make sure your path to the "polykey" executable is correct.
163+
164+
:::
165+
166+
```sh
167+
echo 'export PATH=~/downloads:$PATH' >> ~/.zshrc && source ~/.zshrc
168+
```
83169

84170
You can now run it with `polykey`.
85171

86-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
172+
---
87173

88-
## Windows
174+
#### For Bash:
89175

90-
Polykey-CLI code is compiled, bundled and wrapped into a single file executable.
176+
1. `cd` into the directory where the "polykey" executable is stored.
177+
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.
91178

92-
Builds for Linux is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
179+
:::tip
93180

94-
Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it to `polykey`.
181+
Make sure your path to the "polykey" executable is correct.
182+
183+
:::
184+
185+
```sh
186+
echo 'export PATH=~/downloads:$PATH' >> ~/.bashrc && source ~/.bashrc
187+
```
95188

96189
You can now run it with `polykey`.
97190

98-
In your terminal you can also alias `alias pk='polykey'` for more convenient commands.
191+
---
192+
193+
## Windows
194+
195+
:::danger
196+
197+
Polykey doesn't work on Windows at all as of **20-12-23**, regardless of binaries or building it yourself.
198+
199+
:::
200+
201+
202+
Builds for Windows are released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
203+
204+
Download the executable named `...-polykey-cli-V.V.V-win32-x64`, and rename it to `polykey.exe`.
205+
206+
207+
208+
#### Add to PATH
209+
210+
1. Run the following when you are in the same directory as ``polykey.exe``.
211+
212+
```shell
213+
setx PATH "%PATH%;%CD%" /M
214+
```
215+
:::tip
216+
217+
Make sure you're in the correct directory where "polykey.exe" is placed.
218+
219+
:::
220+
221+
2. Now you can run polykey system-wide by using ``polykey``.
99222

100223
## Docker
101224

@@ -113,6 +236,71 @@ image="$(cut -d' ' -f3 <<< "$loaded")"
113236
docker run -it "$image"
114237
```
115238

239+
### Docker for Mac
240+
241+
:::tip
242+
243+
You can install nix for MacOS and then follow the general docker instructions above.
244+
Nix for mac can be installed by running
245+
246+
```sh
247+
sh <(curl -L https://nixos.org/nix/install)
248+
```
249+
:::
250+
251+
1. Download the latest build of Polykey-CLI for docker from https://polykey.com/download.
252+
253+
2. Download Docker for MacOS depending on your instruction-set (arm vs x86) from https://docs.docker.com/desktop/install/mac-install/
254+
255+
3. Rename the Polykey dist from ``x-docker-image-polykey-cli-x.x.x-alpha.x.tar.gz`` to ``docker-polykey.tar.gz``
256+
257+
4. Load the image in docker using the following:
258+
259+
```shell
260+
docker load --input docker-polykey.tar.gz
261+
```
262+
263+
5. Go to your docker application and configure the Polykey image
264+
265+
![img.png](../../../images/docker-mac-img1.png)
266+
267+
6. Run ```mkdir /tmp/polykey``` to create a directory for the polykey nodepath
268+
269+
7. Set the volume host path to ```/tmp/polykey``` and the container path to ```/tmp/polykey/```
270+
271+
8. Run ``docker images`` to grab the Image ID of your installed image.
272+
273+
```shell
274+
> docker images
275+
REPOSITORY TAG IMAGE ID CREATED SIZE
276+
polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 days ago 370MB
277+
```
278+
279+
9. Now you can run Polykey as an agent with the following shell command
280+
281+
```shell
282+
docker run -it 0e1addd9855a agent start --background -np /tmp/polykey
283+
```
284+
285+
Making sure to replace ``0e1addd9855a`` with your corresponding image ID.
286+
287+
288+
```shell
289+
 docker run -it 0e1addd9855a agent start --background -np /tmp/polykey
290+
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
291+
✔ Enter new password … *
292+
✔ Confirm new password … *
293+
pid 28
294+
nodeId vflhiouqt255gq22drpf0s639kl9eds3ralu094c6rsnmonemp6pg
295+
clientHost 127.0.0.1
296+
clientPort 45509
297+
agentHost ::
298+
agentPort 37468
299+
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
300+
301+
```
302+
303+
116304
## Node Package Manager
117305
118306
The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli).

0 commit comments

Comments
 (0)