extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2024-11-07 08:44:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #750 from openziti/organize-invite-doc

Browse Source 
organize self-service invitation doc
This commit is contained in:
Kenneth Bingham 2024-09-26 16:11:15 -04:00 committed by GitHub
commit 76c67c35bb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 73 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/getting-started.mdx
View File

@ -9,24 +9,9 @@ import DownloadCard from '@site/src/components/download-card';
import DownloadCardStyles from '@site/src/css/download-card.module.css'; import DownloadCardStyles from '@site/src/css/download-card.module.css';
## Choose Your Path ## Get an Account
<Columns className='text--center getting-started-cards'> <Columns className='text--center getting-started-cards'>
<Column style={{paddingBottom: 20}}>
<Card shadow='tl'>
<CardHeader>
<h3>Self-Hosted zrok</h3>
</CardHeader>
<CardBody>
Run a zrok instance on Linux, Docker, or Kubernetes.
</CardBody>
<CardFooter>
<a href="/docs/category/self-hosting/">
<button className='button button--secondary button--block'>Guides</button>
</a>
</CardFooter>
</Card>
</Column>
<Column style={{paddingBottom: 20}}> <Column style={{paddingBottom: 20}}>
<Card shadow='tl'> <Card shadow='tl'>
<CardHeader> <CardHeader>
@ -42,6 +27,21 @@ import DownloadCardStyles from '@site/src/css/download-card.module.css';
</CardFooter> </CardFooter>
</Card> </Card>
</Column> </Column>
<Column style={{paddingBottom: 20}}>
<Card shadow='tl'>
<CardHeader>
<h3>Self-Hosted zrok</h3>
</CardHeader>
<CardBody>
Run a zrok instance on Linux, Docker, or Kubernetes.
</CardBody>
<CardFooter>
<a href="/docs/category/self-hosting/">
<button className='button button--secondary button--block'>Guides</button>
</a>
</CardFooter>
</Card>
</Column>
</Columns> </Columns>
@ -96,51 +96,10 @@ If [sharing privately](./concepts/sharing-private.md), only users with the share
</div> </div>
</AssetsProvider> </AssetsProvider>
## Generating an Invitation
:::note
If not using `zrok.io` (zrok-as-a-service), you must configure the `zrok` command to use your instance. See the [instance configuration guide](/guides/self-hosting/instance-configuration.mdx) in the self-hosting section for details.
:::
Invite yourself to `zrok` by running the `zrok invite` command:
```text
zrok invite
```
```buttonless title="Output"
enter and confirm your email address...
> user@domain.com
> user@domain.com
[ Submit ]
invitation sent to 'user@domain.com'!
```
The `zrok invite` command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the `[ Submit ]` button will send the request to your configured `zrok` service.
Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your `zrok` account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:
![Enter a Password](images/zrok_verify.png)
Enter a password and its confirmation, and click the `Register Account` button. You'll see the following:
![Successful Registration](images/zrok_registration_success.png)
For now, we'll ignore the "enable your shell for zrok" section. Just click the `zrok web portal` link:
![Web Login](images/zrok_web_login.png)
After clicking the `Log In` button, you'll be brought into the `zrok` _web console_:
![Web Console; Empty](images/zrok_web_console_empty.png)
Congratulations! Your `zrok` account is ready to go!
## Enabling Your zrok Environment ## Enabling Your zrok Environment
After you have [an account](#get-an-account), you can enable your `zrok` environment.
A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator. A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator.
When your `zrok` account was created, the service generated a _secret token_ that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a _secret_, protect it. When your `zrok` account was created, the service generated a _secret token_ that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a _secret_, protect it.
@ -371,7 +330,7 @@ Here's a quick review of the `zrok` mental model and the vocabulary.
You create an _account_ with a `zrok` _instance_. Your account is identified by a username and a password, which you use to log into the _web console_. Your account also has a _secret token_, which you will use to authenticate from the `zrok` command-line to interact with the _instance_. You create an _account_ with a `zrok` _instance_. Your account is identified by a username and a password, which you use to log into the _web console_. Your account also has a _secret token_, which you will use to authenticate from the `zrok` command-line to interact with the _instance_.
You create a new _account_ with a `zrok` _instance_ through the `zrok invite` command. You create a new _account_ with NetFoundry's `zrok` _instance_ by subscribing in [myzrok.io](https://myzrok.io) or in a self-hosted `zrok` _instance_ by running [the `zrok invite` command](/guides/self-hosting/self-service-invite.mdx).
### Environment ### Environment

54
docs/guides/self-hosting/self-service-invite.mdx Normal file
View File

@ -0,0 +1,54 @@
---
title: Invitations
---
This is how to set up self-service invitations for your users to get an account on your self-hosted zrok instance.
## Overview
- You can create user accounts directly with the `zrok admin` CLI or API.
- You can welcome users to invite themselves via email.
- You can generate invitation tokens if you want to restrict self-service invitations.
- To enable self-service invitations you must also configure the controller to send email.
## The Self-Service User Experience
This is what your users will do.
```bash
zrok invite
```
```buttonless title="Output"
enter and confirm your email address...
> user@domain.com
> user@domain.com
[ Submit ]
invitation sent to 'user@domain.com'!
```
## How it Works
The `zrok invite` command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the `[ Submit ]` button will start the invitation process.
Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your `zrok` account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account.
![Enter a Password](/zrok_verify.png)
Enter a password and its confirmation, and click the `Register Account` button. You'll see the following:
![Successful Registration](/zrok_registration_success.png)
For now, we'll ignore the "enable your shell for zrok" section. Just click the `zrok web portal` link:
![Web Login](/zrok_web_login.png)
After clicking the `Log In` button, you'll be brought into the `zrok` _web console_:
![Web Console; Empty](/zrok_web_console_empty.png)
Congratulations! Your `zrok` account is ready to go!