diff --git a/.github/workflows/deploy-doc-site.yml b/.github/workflows/deploy-doc-site.yml index 01482a52..7b0d81cd 100644 --- a/.github/workflows/deploy-doc-site.yml +++ b/.github/workflows/deploy-doc-site.yml @@ -1,47 +1,47 @@ -name: Deploy Doc Site - -on: - push: - branches: - - main - -# allow GITHUB_TOKEN to be used by the peaceiris/actions-gh-pages action to push to gh-pages branch -permissions: - contents: write - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - - uses: actions/setup-node@v3 - name: setup npm - with: - node-version: 18 - check-latest: true - cache: "npm" - cache-dependency-path: website/package-lock.json - - - name: Run a multi-line script - run: | - npm install - npm run build - working-directory: website - - # Popular action to deploy to GitHub Pages: - # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - # Build output to publish to the `gh-pages` branch: - publish_dir: ./website/build - # The following lines assign commit authorship to the official - # GH-Actions bot for deploys to `gh-pages` branch: - # https://github.com/actions/checkout/issues/13#issuecomment-724415212 - # The GH actions bot is used by default if you didn't specify the two fields. - # You can swap them out with your own user credentials. - #user_name: github-actions[bot] - #user_email: 41898282+github-actions[bot]@users.noreply.github.com +name: Deploy Doc Site + +on: + push: + branches: + - main + +# allow GITHUB_TOKEN to be used by the peaceiris/actions-gh-pages action to push to gh-pages branch +permissions: + contents: write + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - uses: actions/setup-node@v3 + name: setup npm + with: + node-version: 18 + check-latest: true + cache: "npm" + cache-dependency-path: website/package-lock.json + + - name: Run a multi-line script + run: | + npm install + npm run build + working-directory: website + + # Popular action to deploy to GitHub Pages: + # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + # Build output to publish to the `gh-pages` branch: + publish_dir: ./website/build + # The following lines assign commit authorship to the official + # GH-Actions bot for deploys to `gh-pages` branch: + # https://github.com/actions/checkout/issues/13#issuecomment-724415212 + # The GH actions bot is used by default if you didn't specify the two fields. + # You can swap them out with your own user credentials. + #user_name: github-actions[bot] + #user_email: 41898282+github-actions[bot]@users.noreply.github.com diff --git a/docs/_attic/network/_category_.json b/docs/_attic/network/_category_.json index 771a75a0..4acef57b 100644 --- a/docs/_attic/network/_category_.json +++ b/docs/_attic/network/_category_.json @@ -1,7 +1,7 @@ -{ - "label": "Network", - "position": 60, - "link": { - "type": "generated-index", - } +{ + "label": "Network", + "position": 60, + "link": { + "type": "generated-index", + } } \ No newline at end of file diff --git a/docs/_attic/sharing/_category_.json b/docs/_attic/sharing/_category_.json index 8c046ccc..e6277e75 100644 --- a/docs/_attic/sharing/_category_.json +++ b/docs/_attic/sharing/_category_.json @@ -1,7 +1,7 @@ -{ - "label": "Sharing", - "position": 20, - "link": { - "type": "generated-index", - } +{ + "label": "Sharing", + "position": 20, + "link": { + "type": "generated-index", + } } \ No newline at end of file diff --git a/docs/concepts/_category_.json b/docs/concepts/_category_.json index ce039221..430f3573 100644 --- a/docs/concepts/_category_.json +++ b/docs/concepts/_category_.json @@ -1,8 +1,8 @@ -{ - "label": "Concepts", - "position": 30, - "link": { - "type": "doc", - "id": "concepts/index" - } -} +{ + "label": "Concepts", + "position": 30, + "link": { + "type": "doc", + "id": "concepts/index" + } +} diff --git a/docs/concepts/files.md b/docs/concepts/files.md index 2c1aa620..9b436618 100644 --- a/docs/concepts/files.md +++ b/docs/concepts/files.md @@ -1,52 +1,52 @@ ---- -title: Sharing Websites and Files -sidebar_position: 30 ---- - -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 --rw-r--r--+ 1 Michael None 7090 Apr 17 12:53 CHANGELOG.md --rw-r--r--+ 1 Michael None 11346 Apr 17 12:53 LICENSE --rw-r--r--+ 1 Michael None 2885 Apr 17 12:53 README.md --rwxr-xr-x+ 1 Michael None 44250624 Apr 17 13:00 zrok.exe* -``` - -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_share_web_files](../images/zrok_share_web_files.png) - -`zrok` will automatically provide a stock website, which will allow the accessing user to browse and navigate the file tree. Clicking the files allows the user to download them. - -`zrok` can also share a pre-rendered static HTML website. If you have a directory like this: - -```shell --rw-rw-r--+ 1 Michael None 56 Jun 26 13:23 index.html -``` - -If `index.html` contains valid HTML, like this: - -```html - - -

Hello zrok

- -``` - -Sharing the directory will result in the following when you access the share in a web browser: - -![zrok_share_web_website](../images/zrok_share_web_website.png) - +--- +title: Sharing Websites and Files +sidebar_position: 30 +--- + +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 +-rw-r--r--+ 1 Michael None 7090 Apr 17 12:53 CHANGELOG.md +-rw-r--r--+ 1 Michael None 11346 Apr 17 12:53 LICENSE +-rw-r--r--+ 1 Michael None 2885 Apr 17 12:53 README.md +-rwxr-xr-x+ 1 Michael None 44250624 Apr 17 13:00 zrok.exe* +``` + +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_share_web_files](../images/zrok_share_web_files.png) + +`zrok` will automatically provide a stock website, which will allow the accessing user to browse and navigate the file tree. Clicking the files allows the user to download them. + +`zrok` can also share a pre-rendered static HTML website. If you have a directory like this: + +```shell +-rw-rw-r--+ 1 Michael None 56 Jun 26 13:23 index.html +``` + +If `index.html` contains valid HTML, like this: + +```html + + +

Hello zrok

+ +``` + +Sharing the directory will result in the following when you access the share in a web browser: + +![zrok_share_web_website](../images/zrok_share_web_website.png) + `zrok` contains a built-in web server, which you can use to serve static websites as a share. \ No newline at end of file diff --git a/docs/concepts/hosting.md b/docs/concepts/hosting.md index 08c28a31..95f3dc42 100644 --- a/docs/concepts/hosting.md +++ b/docs/concepts/hosting.md @@ -1,16 +1,16 @@ ---- -sidebar_position: 200 ---- - -# Hosting - -## Self-Hosted - -`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/self_hosting_guide.md) instance 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. +--- +sidebar_position: 200 +--- + +# Hosting + +## Self-Hosted + +`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/self_hosting_guide.md) instance 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. diff --git a/docs/concepts/index.md b/docs/concepts/index.md index fa87094d..6d6c1b00 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -1,13 +1,13 @@ ---- -sidebar_title: Core Features -sidebar_position: 25 ---- - -# Concepts - -`zrok` was designed to make sharing local resources both secure and easy. In this section of the `zrok` documentation, we'll tour through all of the most 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 support for sharing raw [TCP](./tunnels.md) and [UDP](./tunnels.md) network connections, and also includes a [website and file sharing](./files.md) feature. - -Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](../guides/self-hosting/self_hosting_guide.md). +--- +sidebar_title: Core Features +sidebar_position: 25 +--- + +# Concepts + +`zrok` was designed to make sharing local resources both secure and easy. In this section of the `zrok` documentation, we'll tour through all of the most 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 support for sharing raw [TCP](./tunnels.md) and [UDP](./tunnels.md) network connections, and also includes a [website and file sharing](./files.md) feature. + +Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](../guides/self-hosting/self_hosting_guide.md). diff --git a/docs/concepts/opensource.md b/docs/concepts/opensource.md index c6925d6e..b313af23 100644 --- a/docs/concepts/opensource.md +++ b/docs/concepts/opensource.md @@ -1,24 +1,24 @@ ---- -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](https://github.com/openziti/zrok) -for the world to use, inspect, and build upon! - -Check out the repository over on GitHub at [https://github.com/openziti/zrok](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 Ziti _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! +--- +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](https://github.com/openziti/zrok) +for the world to use, inspect, and build upon! + +Check out the repository over on GitHub at [https://github.com/openziti/zrok](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 Ziti _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! diff --git a/docs/concepts/sharing-private.md b/docs/concepts/sharing-private.md index 642c22ae..5858f463 100644 --- a/docs/concepts/sharing-private.md +++ b/docs/concepts/sharing-private.md @@ -1,29 +1,29 @@ ---- -sidebar_position: 0 ---- -# Private Shares - -`zrok` was built to share and access digital resources. A `private` share allows a resource to be -accessed on another user's system as if it were local to them. Privately shared resources can only be accessed by another `zrok` user who has the details of your unique share. You are in control of who can access your `private` shares by sharing the the share token. - -Peer-to-peer private resource sharing is one of the things that makes `zrok` unique. - -`zrok` also provides `public` sharing of resources with non-`zrok` users. Public resource sharing is limited to only resources that can be accessed over `HTTP` or `HTTPS`. `private` sharing works with all of the resources types that `zrok` supports. - -Here's how private sharing works: - -# Peer to Peer - -![zrok_public_share](../images/zrok_private_share.png) - -`private` shares are accessed using the `zrok access` command, and require the accessing user to have a `zrok enable`-d account on the same service instance where the share was created. - -The `private` share is identified by a _share token_. The accessing user will use the share token, along with the `zrok access` command to create a local endpoint on their system, which lets them use the shared resource as if it were local to their system. - -`zrok` does not require you to open any firewall ports or otherwise compromise the security of your local system; there is never an attack surface open to the public internet. As soon as you terminate the `zrok share` process, you immediately terminate any possible access to your shared resource. - -The shared resource can be a development web server to share with friends and colleagues, a webhook from a server running in the cloud which has `zrok` running and has been instructed to `access` the private resource. `zrok` can also share files, websites, and low-level TCP and UDP network connections using the `tunnel` backend. What matters is that the access to the shared resource is not done in a public way, and can only be accessed by other `zrok` users that have access to your share token. - -The peer-to-peer capabilities of `zrok` are an important property of the underlying [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) network that `zrok` uses to provide connectivity between users and resources. - +--- +sidebar_position: 0 +--- +# Private Shares + +`zrok` was built to share and access digital resources. A `private` share allows a resource to be +accessed on another user's system as if it were local to them. Privately shared resources can only be accessed by another `zrok` user who has the details of your unique share. You are in control of who can access your `private` shares by sharing the the share token. + +Peer-to-peer private resource sharing is one of the things that makes `zrok` unique. + +`zrok` also provides `public` sharing of resources with non-`zrok` users. Public resource sharing is limited to only resources that can be accessed over `HTTP` or `HTTPS`. `private` sharing works with all of the resources types that `zrok` supports. + +Here's how private sharing works: + +# Peer to Peer + +![zrok_public_share](../images/zrok_private_share.png) + +`private` shares are accessed using the `zrok access` command, and require the accessing user to have a `zrok enable`-d account on the same service instance where the share was created. + +The `private` share is identified by a _share token_. The accessing user will use the share token, along with the `zrok access` command to create a local endpoint on their system, which lets them use the shared resource as if it were local to their system. + +`zrok` does not require you to open any firewall ports or otherwise compromise the security of your local system; there is never an attack surface open to the public internet. As soon as you terminate the `zrok share` process, you immediately terminate any possible access to your shared resource. + +The shared resource can be a development web server to share with friends and colleagues, a webhook from a server running in the cloud which has `zrok` running and has been instructed to `access` the private resource. `zrok` can also share files, websites, and low-level TCP and UDP network connections using the `tunnel` backend. What matters is that the access to the shared resource is not done in a public way, and can only be accessed by other `zrok` users that have access to your share token. + +The peer-to-peer capabilities of `zrok` are an important property of the underlying [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) network that `zrok` uses to provide connectivity between users and resources. + Creating `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. \ No newline at end of file diff --git a/docs/concepts/sharing-public.md b/docs/concepts/sharing-public.md index fc403bbc..858b78bf 100644 --- a/docs/concepts/sharing-public.md +++ b/docs/concepts/sharing-public.md @@ -1,16 +1,16 @@ ---- -sidebar_position: 10 ---- -# Public Shares - -`zrok` supports `public` sharing for web-based (HTTP and HTTPS) resources. These resources are easily shared with the general internet through public access points. - -## Peer to Public - -![zrok_public_share](../images/zrok_public_share.png) - -`public` sharing is most useful when the person or service accessing your resources does not have `zrok` running locally and cannot make use of the `private` sharing mode built into `zrok`. Many users share development web servers, webhooks, and other HTTP/HTTPS resources. - -As with `private` sharing, `public` sharing does not require you to open any firewall ports or otherwise compromise the security of your local environments. A `public` share goes away as soon as you terminate the `zrok share` command. - +--- +sidebar_position: 10 +--- +# Public Shares + +`zrok` supports `public` sharing for web-based (HTTP and HTTPS) resources. These resources are easily shared with the general internet through public access points. + +## Peer to Public + +![zrok_public_share](../images/zrok_public_share.png) + +`public` sharing is most useful when the person or service accessing your resources does not have `zrok` running locally and cannot make use of the `private` sharing mode built into `zrok`. Many users share development web servers, webhooks, and other HTTP/HTTPS resources. + +As with `private` sharing, `public` sharing does not require you to open any firewall ports or otherwise compromise the security of your local environments. A `public` share goes away as soon as you terminate the `zrok share` command. + Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public` to see the command-line help and to learn how to use `public` shares. \ No newline at end of file diff --git a/docs/concepts/sharing-reserved.md b/docs/concepts/sharing-reserved.md index 5f0410fb..4fec2360 100644 --- a/docs/concepts/sharing-reserved.md +++ b/docs/concepts/sharing-reserved.md @@ -1,14 +1,14 @@ ---- -sidebar_position: 10 ---- -# Reserved Shares - -By default a `public` or `private` share is assigned a _share token_ when you create a share using the `zrok share` command. The `zrok share` command is the bridge between your local environment and the users you are sharing with. When you terminate the `zrok share`, the bridge is eliminated and the _share token_ is deleted. If you run `zrok share` again, you will be allocated a brand new _share token_. - -You can use a `reserved` share to persist your _share token_ across multiple runs of the `zrok share` bridge. When you use a `reserved` share, the share token will not be deleted between multiple runs of `zrok share`. - -To use a `reserved` share, you will first run the `zrok reserve` command to create the reserved share (see `zrok reserve --help` for details). Once you've created your `reserved` share, you will use the `zrok share reserved` command (see `--help` for details) to run the bridge for the shared resource. - -This pattern works for both `public` and `private` shares, and for all resource types supported by `zrok`. - -To delete your `reserved` share use the `zrok release` command or click the delete button in the share's _Actions_ tab in the web console. +--- +sidebar_position: 10 +--- +# Reserved Shares + +By default a `public` or `private` share is assigned a _share token_ when you create a share using the `zrok share` command. The `zrok share` command is the bridge between your local environment and the users you are sharing with. When you terminate the `zrok share`, the bridge is eliminated and the _share token_ is deleted. If you run `zrok share` again, you will be allocated a brand new _share token_. + +You can use a `reserved` share to persist your _share token_ across multiple runs of the `zrok share` bridge. When you use a `reserved` share, the share token will not be deleted between multiple runs of `zrok share`. + +To use a `reserved` share, you will first run the `zrok reserve` command to create the reserved share (see `zrok reserve --help` for details). Once you've created your `reserved` share, you will use the `zrok share reserved` command (see `--help` for details) to run the bridge for the shared resource. + +This pattern works for both `public` and `private` shares, and for all resource types supported by `zrok`. + +To delete your `reserved` share use the `zrok release` command or click the delete button in the share's _Actions_ tab in the web console. diff --git a/docs/guides/_category_.json b/docs/guides/_category_.json index 48ba0588..06389212 100644 --- a/docs/guides/_category_.json +++ b/docs/guides/_category_.json @@ -1,7 +1,7 @@ -{ - "label": "Guides", - "position": 50, - "link": { - "type": "generated-index" - } -} +{ + "label": "Guides", + "position": 50, + "link": { + "type": "generated-index" + } +} diff --git a/docs/guides/install/_category_.json b/docs/guides/install/_category_.json index 5f5e9739..b7acc861 100644 --- a/docs/guides/install/_category_.json +++ b/docs/guides/install/_category_.json @@ -1,8 +1,8 @@ -{ - "label": "Install", - "position": 10, - "link": { - "type": "doc", - "id": "guides/install/index" - } -} +{ + "label": "Install", + "position": 10, + "link": { + "type": "doc", + "id": "guides/install/index" + } +} diff --git a/website/static/img/logo-apple.svg b/website/static/img/logo-apple.svg index edad61a9..f372d9d2 100644 --- a/website/static/img/logo-apple.svg +++ b/website/static/img/logo-apple.svg @@ -1,47 +1,47 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file