From 33c1484caa0b3e0012c5cf9e356829724cff6cb2 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Tue, 21 Nov 2023 14:17:35 -0500 Subject: [PATCH] distinguish between Linux users who want the CLI vs. the system service in the getting started page --- docs/getting-started.md | 99 ++++++++++++++++++++++++++++++----------- 1 file changed, 73 insertions(+), 26 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 31ccc8f25..57532cb71 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -26,28 +26,58 @@ Let's take a look at how to get started with `zrok`. ## Downloading zrok -Releases are also available from the `zrok` project repository on GitHub at https://github.com/openziti/zrok/releases/latest. If you're a Linux user check out [the Linux Service guide](/guides/linux-service.md). +### Install Linux Package -### Extract zrok Distribution +You can install `zrok` from the OpenZiti Linux package repo with these steps. DEB and RPM packages are available for amd64, arm64, and armv7 architectures. + +1. Download the OpenZiti install script. + + ```text + curl -sSo ./openziti-install.bash https://get.openziti.io/install.bash + ``` + +1. Inspect the script to ensure it is suitable to run as root on your system. + + ```text + less ./openziti-install.bash + ``` + +1. Run the script as root to install the `zrok` package. + + ```text + sudo bash ./openziti-install.bash zrok + ``` + +Check out [the Linux Service guide](/guides/linux-service.md) for running `zrok` as a Linux system service. + +### Extract Binary Distribution + +Releases are also available from the `zrok` project repository on GitHub at https://github.com/openziti/zrok/releases/latest. Move the downloaded `zrok` distribution into a directory on your system. In my case, I've placed it in my home directory: +```text +ls -lF zrok* ``` -$ ls -lF zrok* + +```buttonless title="Output" -rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz* ``` Create a directory where the extracted distribution will sit: -``` -$ mkdir zrok -$ cd zrok/ +```text +mkdir zrok +cd zrok/ ``` Extract the `zrok` distribution: +```text +tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz ``` -$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz + +```buttonless title="Output" CHANGELOG.md README.md zrok @@ -59,26 +89,29 @@ Add `zrok` to your shell's environment. For Linux or macos: -``` -$ export PATH=`pwd`:$PATH +```text +export PATH=`pwd`:$PATH ``` For Windows (using Command Prompt): -``` -> set PATH=%CD%;%PATH% +```text +set PATH=%CD%;%PATH% ``` For Windows (using PowerShell): -``` +```text $env:path += ";"+$pwd.Path ``` With the `zrok` executable in your path, you can then execute the `zrok` command from your shell: +```text +./zrok version ``` -$ ./zrok version + +```buttonless title="Output" _ _____ __ ___ | | __ |_ / '__/ _ \| |/ / @@ -100,8 +133,11 @@ This section is relevant if you want to use the `zrok` CLI with an alternate ser The `zrok` executable defaults to using the `zrok` service instance at `api.zrok.io`. Should you need to change the endpoint to use a different service instance, you can do that with the following command: +```text +zrok config set apiEndpoint https://zrok.mydomain.com ``` -$ zrok config set apiEndpoint https://zrok.mydomain.com + +```buttonless title="Output" [WARNING]: unable to open environment metadata; ignoring zrok configuration updated @@ -113,9 +149,11 @@ The `WARNING` about `environment metadata` is ignorable. Running the `zrok confi You can use the `zrok status` command to inspect the state of your local _environment_. `zrok` refers to each shell where you install and `enable` a copy of `zrok` as as an _environment_. +```text +zrok status ``` -$ zrok status +```buttonless title="Output" Config: CONFIG VALUE SOURCE @@ -142,9 +180,11 @@ Some environments take advantage of _invitation tokens_, which limit who is able We generate an invitation with the `zrok invite` command. A service instance that allows open registration will provide an input form like this: +```text +zrok invite ``` -$ zrok invite +```buttonless title="Output" enter and confirm your email address... > user@domain.com @@ -157,9 +197,11 @@ invitation sent to 'user@domain.com'! A service instance that requires token-based invitation authentication will present a form that looks like this: +```text +zrok invite ``` -$ zrok invite +```buttonless title="Output" enter and confirm your email address... If you don't already have one, request an invite token at: michael@quigley.com @@ -206,23 +248,25 @@ This dialog box shows you the `zrok enable` command that you can use to enable a Let's copy that command and paste it into your shell: -``` +```buttonless title="Example" $ zrok enable klFEoIi0QAg7 ⣻ contacting the zrok service... ``` After a few seconds, the message will change and indicate that the enable operation succeeded: -``` +```buttonless title="Example" $ zrok enable klFEoIi0QAg7 ⣻ the zrok environment was successfully enabled... ``` Now, if we run a `zrok status` command, you will see the details of your environment: +```txt +zrok status ``` -$ zrok status +```buttonless title="Output" Config: CONFIG VALUE SOURCE @@ -286,8 +330,11 @@ In this case my share was given the "share token" of `2ptgbr8tlfvk`. That URL ca :::note Here is the `--help` output from `zrok share public`: +```text +zrok share public ``` -$ zrok share public + +```buttonless title="Output" Error: accepts 1 arg(s), received 0 Usage: zrok share public [flags] @@ -338,13 +385,13 @@ If we try to reload the frontend endpoint in our web browser, we'll see: `zrok` also provides a powerful _private_ sharing model. If I execute the following command: -``` +```buttonless title="Example" $ zrok share private http://localhost:8080 ``` The `zrok` service will respond with the following: -``` +```buttonless title="Output" access your share with: zrok access private wvszln4dyz9q ``` @@ -370,7 +417,7 @@ A reserved share can be re-used multiple times; it will survive termination of t The first step is to create the reserved share: -``` +```txt title="Example" $ zrok reserve public --backend-mode web v0.3_getting_started [ 0.275] INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2' [ 0.275] INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io @@ -388,7 +435,7 @@ This is the `404` error message returned by the `zrok` frontend. We're getting t This command: -``` +```txt title="Example" $ zrok share reserved mltwsinym1s2 ``` @@ -404,7 +451,7 @@ With the reserved share, we're free to stop and restart the `zrok share reserved When we're done with the reserved share, we can _release_ it using this command: -``` +```txt title="Example" $ zrok release mltwsinym1s2 [ 0.230] INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released ```