extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2024-11-21 23:53:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

add frontdoor guide

Browse Source
This commit is contained in:
Kenneth Bingham 2023-11-27 15:21:39 -05:00
parent 594c1eb585
commit 37459aabd5
No known key found for this signature in database
GPG Key ID: 31709281860130B6
19 changed files with 282 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/concepts/files.md
View File

@ -1,7 +1,7 @@
---
title: Sharing Websites and Files
sidebar_position: 30
---
# Sharing Websites and Files
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`.
@ -10,6 +10,7 @@ Running with this mode will make it trivially easy to share files from the direc
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
@ -18,6 +19,7 @@ For example if you have a directory with a structure like this:
```
The files can be shared using a command such as:
```shell
zrok share public --backend-mode web .
```

1
docs/concepts/hosting.md
View File

@ -1,6 +1,7 @@
---
sidebar_position: 200
---
# Hosting
## Self-Hosted

1
docs/concepts/index.md
View File

@ -2,6 +2,7 @@
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.

3
docs/concepts/opensource.md
View File

@ -1,12 +1,13 @@
---
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. If you find `zrok` to be useful, and
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.

106
docs/getting-started.mdx
View File

@ -10,7 +10,7 @@ import styles from '@site/src/css/download-card.module.css';
## What's a zrok?
`zrok` is an open-source, self-hostable sharing platform that simplifies sharing network services or files. There's a hardened zrok-as-a-service offering available at [zrok.io](https://zrok.io) with a generous free tier.
`zrok` */ziːɹɒk/ ("zee-rock")* is a secure, open-source, self-hostable sharing platform that simplifies shielding and sharing network services or files. There's a hardened zrok-as-a-service offering available at [zrok.io](https://zrok.io) with a generous free tier.
## Open Source
@ -18,7 +18,9 @@ import styles from '@site/src/css/download-card.module.css';
Check [the roadmap](https://github.com/orgs/openziti/projects/16) if you're thinking about the future. We would love to hear your ideas for `zrok`!
The best ways to engage are [Discourse](https://openziti.discourse.group/) and [GitHub Issues](https://github.com/openziti/zrok/issues).
The best ways to engage are [Discourse](https://openziti.discourse.group/) for questions and [GitHub Issues](https://github.com/openziti/zrok/issues) for documenting problems.
[Read more about zrok open source](/concepts/opensource.md).
### Ziti native
@ -26,7 +28,7 @@ The best ways to engage are [Discourse](https://openziti.discourse.group/) and [
## What's it for?
Use `zrok` to share a running service, like a web server or a UDP socket, or to share a directory of static files.
Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files.
If [sharing publicly](./concepts/sharing-public.md), you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.
@ -57,64 +59,13 @@ If [sharing privately](./concepts/sharing-private.md), only users with the share
</div>
</AssetsProvider>
## Configure Your zrok Service Instance
:::note
Most users can safely skip this section and proceed to "Generating an Invitation" below.
This section is relevant if you want to use the `zrok` CLI with an alternate service instance (in the case of self-hosting, etc.).
:::
`zrok` is both an installable utility that you interact with from your local computer, and also a _service_ that exists on the network. NetFoundry operates the public _service instance_ that is available at `api.zrok.io`, but because `zrok` is open source and self-hostable, you're free to create your own `zrok` service instance.
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
```
```buttonless title="Output"
[WARNING]: unable to open environment metadata; ignoring
zrok configuration updated
```
:::note
The `WARNING` about `environment metadata` is ignorable. Running the `zrok config set` command writes a small piece of metadata into a `.zrok` folder inside your home directory. This allows `zrok` to identify the version of its settings, providing a mechanism to upgrade your installation as new versions are released. This `WARNING` is letting you know that your current environment has not been initialized by `zrok`.
:::
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
```
```buttonless title="Output"
Config:
CONFIG VALUE SOURCE
apiEndpoint https://zrok.mydomain.com config
[WARNING]: Unable to load your local environment!
To create a local environment use the zrok enable command.
```
:::note
The `WARNING` about being `unable to load your local environment` will go away once you've successfully enabled (`zrok enable`) for your shell (we'll get to that below). For now, this warning is ignorable.
:::
The `zrok status` command shows the configured API service that your environment is using, as well as the `SOURCE` where the setting was retrieved. In this case, `config` means that the setting was set into the environment using the `zrok config` command.
## Generating an Invitation
In order to create an account with the `zrok` service instance, you will need to create an invitation.
:::note
Some environments take advantage of _invitation tokens_, which limit who is able to request an invitation on the service instance. If your service uses invitation tokens, the administrator of your instance will include details about how to use your token to generate your invitation.
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.
:::
We generate an invitation with the `zrok invite` command. A service instance that allows open registration will provide an input form like this:
Invite yourself to `zrok` by running the `zrok invite` command:
```text
zrok invite
@ -131,32 +82,13 @@ enter and confirm your email address...
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
```
```buttonless title="Output"
enter and confirm your email address...
If you don't already have one, request an invite token at: michael@quigley.com
> Email Address
> Confirm Email
> Token
[ Submit ]
```
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 it's confirmation, and click the `Register Account` button. You'll see the following:
Enter a password and its confirmation, and click the `Register Account` button. You'll see the following:
![Successful Registration](images/zrok_registration_success.png)
@ -253,15 +185,13 @@ Shared resources are _ephemeral_ by default; as soon as you terminate the `zrok
### Public Shares and Frontends
Resources that are shared _publicly_ are exposed to any users on the internet who have access to the `zrok` service instance's "frontend".
Resources that are shared _publicly_ are exposed to any users on the internet who have access to the `zrok` instance's "frontend".
A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources.
For example, I might create a public share using the `zrok share public` command, which results in my `zrok` service instance exposing the following URL to access my resources:
For example, I might create a public share using the `zrok share public` command, which results in my `zrok` instance exposing a URL like `https://2ptgbr8tlfvk.share.zrok.io` to access my resources.
https://2ptgbr8tlfvk.share.zrok.io
In this case my share was given the "share token" of `2ptgbr8tlfvk`. That URL can be given to any user, allowing them to immediately access the shared resources directly from my local environment, all without exposing any access to my private, secure environment. The physical network location of my environment is not exposed to anonymous consumers of my resources.
In this case, my share was given the "share token" of `2ptgbr8tlfvk`. That URL can be given to any user, allowing them to immediately access the shared resources directly from my local environment, all without exposing any access to my private, secure environment. The physical network location of my environment is not exposed to anonymous consumers of my resources.
:::note
Here is the `--help` output from `zrok share public`:
@ -381,7 +311,7 @@ $ zrok share reserved mltwsinym1s2
And now if we refresh the frontend endpoint URL in the web browser, we'll see an index of the `docs` directory:
![zrok docs share](images/zrok_docs_share.png)
![zrok docs share](images/zrok_web_console_share_frontend.png)
With the reserved share, we're free to stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share.
@ -398,11 +328,11 @@ In summary, `zrok` lets you easily and securely share resources with both genera
Here's a quick review of the `zrok` mental model and the vocabulary.
### Service Instance and Account
### Instance and Account
You create an _account_ with a `zrok` _service 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 _service 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` _service instance_ through the `zrok invite` command.
You create a new _account_ with a `zrok` _instance_ through the `zrok invite` command.
### Environment
@ -414,7 +344,7 @@ You create a new _environment_ by using the `zrok enable` command.
Once you've enabled an _environment_, you then create one or more _shares_. Shares have either a _public_ or _private_ _sharing mode_. _Shares_ share a specific type of resource using a _backend mode_. As of this writing `zrok` supports a `proxy` _backend mode_ to share local HTTP resources as a _reverse proxy_. `zrok` also supports a `web` _backend mode_ to share local file and HTML resources by enabling a basic HTTP server.
Every _share_ is identified by a _share token_. _Public shares_ can be accessed through either a _frontend_ instance offered through the `zrok` _service instance_, or through the `zrok access` command. _Private shares_ can only be accessed through the `zrok access` command.
Every _share_ is identified by a _share token_. _Public shares_ can be accessed through either a _frontend_ instance offered through the `zrok` _instance_, or through the `zrok access` command. _Private shares_ can only be accessed through the `zrok access` command.
You use the `zrok share` command to create and enable _ephemeral shares_.
@ -424,9 +354,9 @@ You use the `zrok share` command to create and enable _ephemeral shares_.
You use the `zrok reserve` command to create _reserved shares_. Reserved shares last until you use the `zrok release` command to delete them.
## Self-Hosting a Service Instance
## Self-Hosting an Instance
Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](./guides/self-hosting/self_hosting_guide.md) for details.
Interested in self-hosting your own `zrok` instance? See the [self-hosting guide](./guides/self-hosting/self_hosting_guide.md) for details.
[openziti]: https://docs.openziti.io/docs/learn/introduction/ "OpenZiti"
[ zrok-download]: https://zrok.io "zrok Download"

4
docs/guides/linux-frontdoor.md → docs/guides/_linux-service.mdx
View File

@ -1,6 +1,6 @@
---
title: zrok frontdoor
sidebar_label: frontdoor
title: zrok system service
sidebar_label: Linux Service
sidebar_position: 40
---

93
docs/guides/docker-share/_reserved_public_share.mdx Normal file
View File

@ -0,0 +1,93 @@
1. Make a folder on your computer to use as a Docker Compose project for your zrok public share with a reserved subdomain.
1. In your terminal, go to the newly-created project folder.
1. Download [the reserved public share project file](pathname:///zrok-public-reserved/compose.yml) into the project folder.
1. Copy your zrok account's enable token from the zrok web console to your clipboard and paste it in a file named `.env` in the same folder like this:
```bash title=".env"
ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
```
1. Run the Compose project to start sharing the built-in demo web server.
```bash
docker compose up --detach
```
1. Get the public share URL from the output of the `zrok-share` service or by peeking in the zrok console where the share will be graphed.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```
This concludes the minimum steps to begin sharing the demo web server. Read on to learn how to pivot to sharing any website or web service by leveraging additional zrok backend modes.
## Proxy Any Web Server
The simplest way to share your web server is to set `ZROK_TARGET` (e.g. `https://example.com`) in the environment of the `docker compose up` command. When you restart the share will auto-configure for that upstream server URL. This applies to both temporary and reserved public shares.
```bash title=".env"
ZROK_TARGET="http://example.com:8080"
```
```bash
docker compose down && docker compose up
```
## Require Authentication
You can require authentication for your public share by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` if you're using our hosted zrok.io, and any OIDC provider you've configured if self-hosting. You can parse the authenticated email address from the request cookie. Read more about the OAuth features in [this blog post](https://blog.openziti.io/the-zrok-oauth-public-frontend). This applies to both temporary and reserved public shares.
```bash title=".env"
ZROK_OAUTH_PROVIDER="github"
```
## Share Something Different
The reserved public share project uses zrok's `caddy` mode. Caddy accepts configuration as a Caddyfile that is mounted into the container ([zrok Caddyfile examples](https://github.com/openziti/zrok/tree/main/etc/caddy)).
1. Create a Caddyfile. This example demonstrates proxying two HTTP servers with a weighted round-robin load balancer.
```console title="Caddyfile"
http:// {
# zrok requires this bind address template
bind {{ .ZrokBindAddress }}
reverse_proxy /* {
to http://httpbin1:8080 http://httpbin2:8080
lb_policy weighted_round_robin 3 2
}
}
```
1. Create a file `compose.override.yml`. This example adds two `httpbin` containers for Caddy load balance, and masks the default Caddyfile with our custom one.
```yaml title="compose.override.yml"
services:
httpbin1:
image: mccutchen/go-httpbin # 8080/tcp
httpbin2:
image: mccutchen/go-httpbin # 8080/tcp
zrok-share:
volumes:
- ./Caddyfile:/mnt/.zrok/Caddyfile
```
1. Re-run the project to load the new configuration.
```bash
docker compose up --force-recreate --detach
```
1. Recall the reserved share URL from the log.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
```

49
docs/guides/frontdoor.mdx Normal file
View File

@ -0,0 +1,49 @@
---
title: zrok frontdoor
sidebar_label: frontdoor
sidebar_position: 20
---
import OsTabs from '@theme/OsTabs';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
// import Details from '@theme/MDXComponents/Details';
import LinuxService from './_linux-service.mdx';
import ReservedDocker from './docker-share/_reserved_public_share.mdx';
zrok frontdoor is a way of using zrok-as-a-service from [zrok.io](https://zrok.io) as a shielded entry point to your website or service. This is useful if you want to expose a service to the public internet, but don't want to expose the service directly.
<OsTabs
queryString="os"
values={[
{ label: 'Linux', value: 'Linux', },
{ label: 'macOS', value: 'Mac OS', },
{ label: 'Windows', value: 'Windows', },
]}
>
<TabItem value="Linux">
On Linux, zrok frontdoor is implemented as a system service which is provided by the `zrok-share` DEB or RPM package.
<LinuxService/>
</TabItem>
<TabItem value="Mac OS">
On macOS, zrok frontdoor is implemented as a Docker share project which reserves a public subdomain for your website or service.
<ReservedDocker/>
</TabItem>
<TabItem value="Windows">
On Windows, zrok frontdoor is implemented as a Docker share project which reserves a public subdomain for your website or service.
<ReservedDocker/>
</TabItem>
</OsTabs>

2
docs/guides/install/linux.mdx
View File

@ -98,7 +98,7 @@ We recommend that you install `zrok` from the Linux package repository with the
:::info
Check out [the `zrok` Front Door](/guides/linux-frontdoor.md) for running `zrok` as a Linux system service.
Check out [zrok frontdoor](/guides/frontdoor.mdx?os=Linux) for running `zrok` as an always-on service.
:::

46
docs/guides/self-hosting/instance-configuration.mdx Normal file
View File

@ -0,0 +1,46 @@
---
title: Use Another zrok Instance
sidebar_label: Instance Config
---
:::note
This guide is relevant if you are self-hosting or using a friend's `zrok` instance instead of using zrok-as-a-service from `zrok.io`.
:::
The `zrok` *command* on your omputer uses a `zrok` *instance* over the network.
The default instance API endpoint for the `zrok` command is `api.zrok.io`. Set the API endpoint to another instance's API endpoint:
```text
zrok config set apiEndpoint https://zrok.example.com
```
```buttonless title="Output"
[WARNING]: unable to open environment metadata; ignoring
zrok configuration updated
```
:::note
The `WARNING` about `environment metadata` is expected when you run `zrok config set` before `zrok enable`.
:::
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
```
```buttonless title="Output"
Config:
CONFIG VALUE SOURCE
apiEndpoint https://zrok.mydomain.com config
[WARNING]: Unable to load your local environment!
To create a local environment use the zrok enable command.
```
The `zrok status` command shows the configured API service that your environment is using, as well as the `SOURCE` where the setting was retrieved. In this case, `config` means that the setting was set into the environment using the `zrok config` command.

4
docs/guides/self-hosting/self_hosting_guide.md
View File

@ -24,7 +24,7 @@ I specifically used the "Host OpenZiti Anywhere" variant because it provides a p
Keep track of the generated admin password when running the `expressInstall` script. The script will prompt you like this:
```
```text
Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9fpD'? (Y/n)
```
@ -101,6 +101,8 @@ In my case, I've set:
export ZROK_API_ENDPOINT=http://127.0.0.1:18080
```
[Read more about configuring your self-hosted `zrok` instance](/guides/self-hosting/instance-configuration.mdx).
## Bootstrap OpenZiti for zrok
With your OpenZiti network running and your configuration saved to a local file (I refer to mine as `etc/ctrl.yml` in these examples), you're ready to bootstrap the Ziti network.

BIN
docs/images/zrok_docs_share.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/images/zrok_web_console_share_frontend.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 72 KiB

13
website/package-lock.json generated
View File

@ -15,6 +15,7 @@
"clsx": "^1.2.1",
"prism-react-renderer": "^1.3.5",
"react": "^18.2.0",
"react-device-detect": "^2.2.3",
"react-dom": "^18.2.0",
"remark-math": "^5.1.1"
},
@ -12328,6 +12329,18 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/react-device-detect": {
"version": "2.2.3",
"resolved": "https://registry.npmjs.org/react-device-detect/-/react-device-detect-2.2.3.tgz",
"integrity": "sha512-buYY3qrCnQVlIFHrC5UcUoAj7iANs/+srdkwsnNjI7anr3Tt7UY6MqNxtMLlr0tMBied0O49UZVK8XKs3ZIiPw==",
"dependencies": {
"ua-parser-js": "^1.0.33"
},
"peerDependencies": {
"react": ">= 0.14.0",
"react-dom": ">= 0.14.0"
}
},
"node_modules/react-dom": {
"version": "18.2.0",
"resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.2.0.tgz",

1
website/package.json
View File

@ -21,6 +21,7 @@
"clsx": "^1.2.1",
"prism-react-renderer": "^1.3.5",
"react": "^18.2.0",
"react-device-detect": "^2.2.3",
"react-dom": "^18.2.0",
"remark-math": "^5.1.1"
},

2
website/src/components/assets-context.jsx
View File

@ -18,7 +18,7 @@ export const AssetsProvider = ({ children }) => {
const filteredAssets = data.assets.map(asset => ({
name: asset.name,
url: asset.browser_download_url,
arch: asset.name.replace('\.tar\.gz','').toUpperCase().split('_')[3]
arch: asset.name.replace('\.tar\.gz','').split('_')[3]
}));
console.log("Fetched assets:", filteredAssets); // Log fetched assets
setAssets(filteredAssets);

15
website/src/components/download-card.jsx
View File

@ -17,6 +17,19 @@ const getFilenamePattern = (osName) => {
}
};
const getArchitecturePattern = (arch) => {
switch (arch) {
case 'amd64':
return 'x86_64';
case 'arm64':
return 'ARM64';
case 'armv7':
return 'ARM';
default:
return arch.toUpperCase();
}
}
const DownloadCard = ({ osName, osLogo, infoText, guideLink }) => {
const { colorMode } = useColorMode();
const assets = useAssets();
@ -37,7 +50,7 @@ const DownloadCard = ({ osName, osLogo, infoText, guideLink }) => {
{filteredLinks.map((link, index) => (
<li key={index} className={styles.downloadButtons}>
<a href={link.url} className={styles.downloadLinks}>
{link.arch}
{getArchitecturePattern(link.arch)}
</a>
</li>
))}

2
website/src/css/download-card.module.css
View File

@ -34,7 +34,7 @@
.downloadCard img {
width: auto; /* This will make the image take the full width of the card */
max-height: 150px; /* This will maintain the aspect ratio of the image */
max-height: 100px; /* This will maintain the aspect ratio of the image */
margin: 0 auto; /* Center the image if the card is wider than the image */
display: block; /* Change display from inline to block for better control */
padding: 10px;;

29
website/src/theme/OsTabs/index.js Normal file
View File

@ -0,0 +1,29 @@
import React, { useState, useEffect } from 'react';
import OriginalTabs from '@theme/Tabs';
import { osName } from 'react-device-detect';
function OsTabs(props) {
const [defaultValue, setDefaultValue] = useState(null);
useEffect(() => {
// Based on the OS or any other client-side condition, set the default value
const tabs = ['iOS', 'Android', 'Mac OS', 'Windows', 'Linux']
if (tabs.includes(osName)) {
setDefaultValue(osName);
} else {
setDefaultValue('Windows');
}
}, []); // The empty dependency array ensures this runs once after component mount
return (
<>
<OriginalTabs {...props} defaultValue={defaultValue}>
{props.children}
</OriginalTabs>
{/* Uncomment the following line to debug the detected and selected values */}
{/* <h2>detected={osName}, selected={defaultValue}</h2> */}
</>
);
}
export default OsTabs;