Merge pull request #210 from openziti/core-features

add a core features section stub

README.md

@@ -1,6 +1,6 @@
 ![zrok](docs/images/zrok.png)
 
-`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://docs.openziti.io), a programmable zero-trust network overlay. `zrok` is an OpenZiti _Native Application_.
+`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://docs.openziti.io/docs/learn/introduction/), a programmable zero-trust network overlay. `zrok` is an OpenZiti _Native Application_.
 
 `zrok` facilitates sharing resources both publicly and privately, exposing them to an audience you can easily control.
 

docs/core-features/files.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 30
+---
+# File Sharing
+
+With `zrok` it is possible to share files quickly and easily as well. To share files using `zrok` use
+the `--backend-mode web`, for example: `zrok share private . --backend-mode web`.
+
+Running with this mode will make it trivially easy to share files from the directory which the command
+was run from.
+
+For example if you have a directory with a structure like this:
+```shell
+-rwxrwxrwx 1 cd cd     2506 Jan 26 11:57 README.md
+-rwxrwxrwx 1 cd cd     2971 Jan 26 11:57 CHANGELOG.md
+-rwxrwxrwx 1 cd cd 41544024 Jan 26 12:00 zrok
+```
+
+The files can be shared using a command such as: 
+```shell
+zrok share public . --backend-mode web
+```
+
+Then the files can be access with a `private` or `public` share, for example as shown:
+
+![zrok_public_share](../images/zrok_share_file.png)

docs/core-features/hosting.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 200
+---
+# Hosting
+
+## Self-Hosted
+
+`zrok` is not limited to a managed offering. You can host your own version of `zrok` as well. `zrok` is
+also freely available as open source software hosted by GitHub under a very permissive Apache v2 license.
+
+## Managed Service
+
+`zrok` is also offered as a cloud service, making it instantly accessible to a large population immediately.
+NetFoundry provides a manged version of `zrok` at https://zrok.io. This provides the easy-to-use,
+quick to demonstrate features of `zrok` without needing to deploy and host `zrok` yourself.

docs/core-features/index.md

@@ -0,0 +1,13 @@
+---
+sidebar_title: Core Features
+sidebar_position: 25
+---
+# Core Features
+
+`zrok` was built for sharing resources. This doc is meant to explain the core features of `zrok` sharing
+as well as other important features.
+
+Sharing with `zrok` can be either [`public`](./sharing-public.md) or [`private`](./sharing-private.md).
+Naturally, regular web-based resources can be shared but `zrok` also includes a [file sharing](./files.md) feature.
+
+Learn about `zrok` [hosting here](./hosting.md). 

docs/core-features/opensource.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 100
+---
+# Open Source
+
+It's important to the `zrok` project that it remain free and open source software. The code is available on GitHub
+for the world to use, inspect, and build upon!
+
+Check out the repository over on GitHub at https://github.com/openziti/zrok.  If you find `zrok` to be useful, and
+you want to help spread the word of `zrok` give the project a star. It really does help get the word out about the
+project.
+
+The project also uses a very permissive license: Apache v2. We encourage people to fork the repo and use `zrok` for
+your own purposes how you see fit or contribute back to the project.
+
+## Built on OpenZiti
+
+The power of `zrok` really lies in `private` sharing. It's increasingly clear that security needs to be a first-class
+member of any organization. To enable `private` sharing, `zrok` was built on top of another excellent open source
+project named OpenZiti. 
+
+OpenZiti is a secure overlay network focusing on bringing zero trust to applications. It is the __backbone__ of `zrok`.
+In fact, `zrok` proudly proclaims itself as an OpenZiti _native_ application.
+
+If you are interested in learning more about OpenZiti head over to [the docs](https://docs.openziti.io/docs/learn/introduction/),
+try the quickstart, and don't forget to star that project too. We couldn't build `zrok` without OpenZiti!

docs/core-features/sharing-private.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 0
+---
+# Shares - Private
+
+`zrok` was built to share and access digital resources. A `private` share allows a resource to be 
+shared through a __privately__ available endpoint. Sharing a resource with `private` is __a differentiating__
+feature of `zrok`.
+
+# Peer to Peer
+
+![zrok_public_share](../images/zrok_private_share.png)
+
+A `private` share will require `zrok` to access the share and will also require a special shared 
+secret token. This access token, combined with the `zrok access` command will be how the private share is accessed.
+
+Sharing something with `private` is similar to sharing something publicly. The main difference is
+obvious, the shared resource is `private` and the share is __not__ open to the public. With `zrok`, you
+can share resources on a private network without needing to expose the service to the internet. The share is not 
+through an obfuscated, difficult to guess url. Instead the sharing is accomplished using a secure, zero trust overlay
+network provided by [OpenZiti](https://docs.openziti.io/docs/learn/introduction/). With this private, peer to peer 
+sharing model, there will never an attack surface available to the open internet.
+
+The shared resource can be a development web server to share with friends and colleagues or perhaps,
+it could be a webhook from a server running in the cloud which has `zrok` running and has been instructed
+to `access` the private resource. What matters is that the access to the shared resource __should not__
+be done in a public way, for more secure access.
+
+Using `private` shares is easy and is accomplished using the `zrok share private` command. Run `zrok share private`
+to see the usage output and to further learn how to use the command. 
+
+Unlike public shares, `private` shares do not need to be [reserved](./sharing-reserved.md) to be predictable. When sharing a
+resource with `private`, the resource is shared at a known location. Resources shared with `private` do not
+need to be `reserved`.

docs/core-features/sharing-public.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 10
+---
+# Shares - Public
+
+`zrok` was built to share and access digital resources. a `public` share allows something to be shared through 
+a publicly available endpoint.
+
+## Public Sharing
+
+![zrok_public_share](../images/zrok_public_share.png)
+
+Sharing something with `public` is useful when the person or service accessing the thing being shared doesn't
+have `zrok` running locally and can't make use of the `private` sharing mode built into `zrok`. This could be
+a development web server to share with friends and colleagues, or perhaps a webhook from a
+server running in the cloud which can't have `zrok` installed onto it. What matters is that the access to the
+shared resource needs to be done in a public way, generally for easy access.
+
+Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public`
+to see the usage output and to further learn how to use the command. 
+
+Unless `reserved` (see [Sharing - Reserved](./sharing-reserved.md), all 'public' shares are ephemeral. When the
+sharing is stopped, the shared url will be reclaimed.

docs/core-features/sharing-reserved.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 10
+---
+# Shares - Reserved
+
+`zrok` was built to share and access digital resources. A `reserved` share allows the user to have a reliable,
+public, persistent shared url. (the share name not ephemeral, it is `reserved`). This means that the share
+will be able to be used and regardless of how many times the resource is shared. This is useful when the 
+url must be known. 
+
+Use the `zrok reserve` command to create a reserved share.

docs/getting-started.md

@@ -3,17 +3,31 @@ sidebar_position: 0
 ---
 # Getting Started with zrok
 
-`zrok` is a next-generation sharing platform built on top of [OpenZiti](https://github.com/openziti/ziti/stargazers), a programmable zero trust network overlay. `zrok` is an _OpenZiti Native Application_.
+`zrok` is an open source, Apache v2 licensed sharing platform, built on top of [OpenZiti](https://docs.openziti.io/docs/learn/introduction/), 
+a programmable zero trust network overlay. `zrok` is an _OpenZiti Native Application_. You can choose to self-host `zrok`
+or leverage the free, managed offering provided by NetFoundry: https://zrok.io
 
-`zrok` facilitates sharing resources publicly and privately with an audience of your choosing.
+As of version `v0.3.0`, `zrok` provides the ability to:
 
-As of version `v0.3.0`, `zrok` provides users the ability to publicly proxy local HTTP endpoints (similar to other offerings in this space). Additionally, `zrok` provides the ability to:
-
-* _privately_ share resources with other `zrok` users; in _private_ usage scenarios, your private resources are not exposed to any public endpoints, and all communication is securely and privately transported between `zrok` clients
+* share resources [publicly](./core-features/sharing-public.md), similar to other distributed reverse proxies.
+* share [privately](./core-features/sharing-private.md). It does this by leveraging
+  [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) to support zero trust, peer to peer connections without
+  the need for any open ports on the internet.
 * use `web` sharing; easily share files with others using a single `zrok` command
 
 Let's take a look at how to get started with `zrok`.
 
+:::note `zrok` moves fast!
+
+`zrok` is currently in a closed-beta phase and requires an invitation token. If you would like to try `zrok` and provide
+feedback, please send an email to help@openziti.org. `zrok` is an open source project and is in its early development
+phases. We're doing our development publicly. See the [roadmap](https://github.com/orgs/openziti/projects/16) for details
+about the project. We are highly interested in feedback as we continue to iterate quickly. Please provide feedback in
+[Discourse](https://openziti.discourse.group/), raise [GitHub Issues](https://github.com/openziti/zrok/issues), or reach
+out directly.
+
+:::
+
 ## Downloading zrok
 
 Releases are also available from the `zrok` project repository on GitHub at https://github.com/openziti/zrok/releases/latest
@@ -418,5 +432,5 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares
 
 Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](guides/v0.3_self_hosting_guide.md) for details.
 
-[openziti]: https://docs.openziti.io/	"OpenZiti"
+[openziti]: https://docs.openziti.io/docs/learn/introduction/	"OpenZiti"
 [ zrok-download]: https://zrok.io "Zrok Download"

website/docusaurus.config.js

@@ -70,6 +70,8 @@ const config = {
         logo: {
           alt: 'Ziggy Goes to Space',
           src: 'img/space-ziggy.png',
+          href: 'https://zrok.io',
+          target: '_self',
         },
         items: [
           {
@@ -78,6 +80,11 @@ const config = {
             position: 'right',
             label: 'What is zrok?',
           },
+          {
+            href: 'https://github.com/orgs/openziti/projects/16',
+            label: 'Roadmap',
+            position: 'right',
+          },
           {
             type: 'doc',
             docId: 'getting-started',

website/src/css/custom.css

@@ -169,4 +169,12 @@ a code {
 ::selection {
   color: var(--selection-font-color);
   background: var(--selection-background);
+}
+
+.navbar__link:hover, .navbar__link--active {
+  text-decoration: none;
+}
+.navbar__link {
+  color: var(--ifm-navbar-link-color);
+  font-weight: var(--ifm-font-weight-semibold);
 }