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

Merge branch 'main' of github.com:openziti/zrok into python-sdk

Browse Source
This commit is contained in:
Cam 2023-12-04 15:57:00 -06:00
commit f90f5aebb1
No known key found for this signature in database
GPG Key ID: 367B7C7EBD84A8BD
49 changed files with 8358 additions and 13520 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/deploy-doc-site.yml vendored
View File

@ -19,7 +19,7 @@ jobs:
- uses: actions/setup-node@v3
name: setup npm
with:
node-version: 16
node-version: 18
check-latest: true
cache: "npm"
cache-dependency-path: website/package-lock.json

16
CHANGELOG.md
View File

@ -1,5 +1,21 @@
# CHANGELOG
## v0.4.18
CHANGE: Moved the golang zrok sdk into `sdk/golang/sdk` to normalize location for future sdk's.
## v0.4.17
CHANGE: Replaced most in-line shell scripts in Docker Compose projects with installed scripts that are shared between the Docker and Linux service. This normalizes the operational configuration of both Docker shares and Linux service, i.e., to use the same env vars.
CHANGE: Upgrade to Docusaurus v3 for documentation.
FIX: Some Docker shares had broken env mountpoints
## v0.4.16
FEATURE: Publish Linux packages for `zrok` CLI and a systemd service for running a reserved public share (`zrok-share`).
## v0.4.15
CHANGE: Updated the code signing and notarization process for macos binaries. The previous release process used the `gon` utility to handle both code signing and notarization. Apple changed the requirements and the `gon` utility no longer properly functions as of 2023-11-01. The `goreleaser` process has been adjusted to use the `notarytool` utility that ships with XCode to sign and notarize the binary (https://github.com/openziti/zrok/issues/435)

2
cmd/zrok/reserve.go
View File

@ -8,8 +8,8 @@ import (
"github.com/openziti/zrok/tui"
"github.com/sirupsen/logrus"
"github.com/spf13/cobra"
"time"
"slices"
"time"
)
func init() {

25
docker/compose/zrok-private-access/compose.yml
View File

@ -7,31 +7,24 @@ services:
volumes:
- zrok_env:/mnt/.zrok
# enable zrok environment
zrok-enable:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
depends_on:
zrok-init:
condition: service_completed_successfully
entrypoint:
- bash
- -euc
- |
if [[ -n "$(jq '.ziti_identity' ~/.zrok/environment.json 2>/dev/null)" ]]; then
echo "INFO: zrok environment is already enabled"
exit 0
else
zrok config set apiEndpoint ${ZROK_API_ENDPOINT:-https://api.zrok.io}
echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
exec zrok "$${@}"
fi
command: -- enable --headless --description "${ZROK_ENVIRONMENT_NAME:-docker private access}" ${ZROK_ENABLE_TOKEN}
entrypoint: zrok-enable.bash
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
STATE_DIRECTORY: /mnt
ZROK_ENABLE_TOKEN:
ZROK_API_ENDPOINT:
ZROK_ENVIRONMENT_NAME: docker-private-access
zrok-access:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
restart: unless-stopped
command: access private --headless --bind 0.0.0.0:9191 ${ZROK_ACCESS_TOKEN}
depends_on:
zrok-enable:
@ -39,7 +32,7 @@ services:
ports:
- 9191:9191 # expose the zrok private access proxy to the Docker host
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"

36
docker/compose/zrok-private-share/compose.yml
View File

@ -7,42 +7,42 @@ services:
volumes:
- zrok_env:/mnt/.zrok
# enable zrok environment
zrok-enable:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
depends_on:
zrok-init:
condition: service_completed_successfully
entrypoint:
- bash
- -euc
- |
if [[ -n "$(jq '.ziti_identity' ~/.zrok/environment.json 2>/dev/null)" ]]; then
echo "INFO: zrok environment is already enabled"
exit 0
else
zrok config set apiEndpoint ${ZROK_API_ENDPOINT:-https://api.zrok.io}
echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
exec zrok "$${@}"
fi
command: -- enable --headless --description "${ZROK_ENVIRONMENT_NAME:-docker private share}" ${ZROK_ENABLE_TOKEN}
entrypoint: zrok-enable.bash
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
STATE_DIRECTORY: /mnt
ZROK_ENABLE_TOKEN:
ZROK_API_ENDPOINT:
ZROK_ENVIRONMENT_NAME: docker-private-share
zrok-share:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
command: share private --headless --backend-mode proxy ${ZROK_TARGET:-http://zrok-test:9090/}
restart: no
entrypoint:
- bash
- -euxc
- |
echo "DEBUG: HOME=$${HOME}"
ls -lA /mnt/.zrok/
exec zrok $${@}
command: -- share private --headless --backend-mode proxy ${ZROK_TARGET:-http://zrok-test:9090/}
depends_on:
zrok-enable:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"
# demo servers you can share with zrok
# demo server you can share with zrok
zrok-test:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
command: test endpoint --address 0.0.0.0 # 9090

159
docker/compose/zrok-public-reserved/compose.yml
View File

@ -1,46 +1,7 @@
services:
# create Caddyfile
zrok-caddyfile:
image: busybox
# create Caddyfile
entrypoint:
- sh
- -euc
- |
ZROK_UPSTREAM_URL="${ZROK_TARGET:-http://zrok-test:9090}"
ZROK_UPSTREAM_HOST="$(echo $${ZROK_UPSTREAM_URL}|sed -E 's#^https?://([^/:]+).*#\1#')"
mkdir -p /mnt/.zrok
cat <<CADDYFILE >| /mnt/.zrok/Caddyfile
{
# GET /config/ and POST /load on this API to reload Caddy config
admin 0.0.0.0:2019
}
http:// {
bind {{ .ZrokBindAddress }}
handle_path /zrok-test/* {
reverse_proxy http://zrok-test:9090 {
header_up Host zrok-test
}
}
handle_path /zrok-static/* {
root * /mnt/.zrok/html
file_server browse
}
reverse_proxy /* $${ZROK_UPSTREAM_URL} {
header_up Host $${ZROK_UPSTREAM_HOST}
}
}
CADDYFILE
user: root
volumes:
- zrok_env:/mnt
# set file ownership
zrok-init:
image: busybox
depends_on:
zrok-caddyfile:
condition: service_completed_successfully
# matches uid:gid of "nobody" in zrok container image
command: chown -Rc 65534:65534 /mnt/
user: root
@ -53,116 +14,42 @@ services:
depends_on:
zrok-init:
condition: service_completed_successfully
entrypoint:
- bash
- -euc
- |
if [[ -s ~/.zrok/environment.json ]]; then
ZITI_ID="$(jq '.ziti_identity' ~/.zrok/environment.json 2>/dev/null)"
if [[ -z "$${ZITI_ID}" || "$${ZITI_ID}" == null ]]; then
echo "ERROR: invalid environment; consider a reset with 'docker compose down --volumes'" >&2
exit 1
else
echo "INFO: zrok environment is already enabled"
exit 0
fi
else
if [[ -z "${ZROK_ENABLE_TOKEN}" ]]; then
echo "ERROR: ZROK_ENABLE_TOKEN is not defined" >&2
exit 1
else
zrok config set apiEndpoint ${ZROK_API_ENDPOINT:-https://api.zrok.io}
echo "INFO: running: zrok $(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
exec zrok "$${@}"
fi
fi
command: -- enable --headless --description "${ZROK_ENVIRONMENT_NAME:-docker reserved public share}" ${ZROK_ENABLE_TOKEN}
entrypoint: zrok-enable.bash
volumes:
- zrok_env:/mnt
environment:
HOME: /mnt
STATE_DIRECTORY: /mnt
ZROK_ENABLE_TOKEN:
ZROK_API_ENDPOINT:
ZROK_ENVIRONMENT_NAME: docker-public-reserved
# reserve zrok frontend url for the zrok backend config
zrok-reserve:
# reserve zrok frontend subdomain and start sharing the target
zrok-share:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
entrypoint:
- bash
- -euc
- |
if [[ -s ~/.zrok/reserved.json ]]; then
ZROK_RESERVED_TOKEN="$(jq '.token' ~/.zrok/reserved.json 2>/dev/null)"
if [[ -z "$${ZROK_RESERVED_TOKEN}" || "$${ZROK_RESERVED_TOKEN}" == null ]]; then
echo "ERROR: invalid reserved.json: $(jq -c . ~/.zrok/reserved.json)" >&2
exit 1
else
echo "INFO: zrok backend is already reserved: $${ZROK_RESERVED_TOKEN}"
exit 0
fi
else
set -o pipefail
ZROK_CMD="reserve public --json-output"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
fi
if [[ -n "${ZROK_OAUTH_PROVIDER:-}" ]]; then
ZROK_CMD+=" --oauth-provider ${ZROK_OAUTH_PROVIDER}"
fi
if [[ -n "${ZROK_BACKEND_MODE:-}" && "${ZROK_BACKEND_MODE}" != caddy ]]; then
ZROK_CMD+=" --backend-mode ${ZROK_BACKEND_MODE} ${ZROK_TARGET:-http://zrok-test:9090}"
else
ZROK_CMD+=" --backend-mode caddy /mnt/.zrok/Caddyfile"
fi
echo "INFO: running: zrok $${ZROK_CMD}"
zrok $${ZROK_CMD} | jq -rc | tee ~/.zrok/reserved.json
fi
restart: unless-stopped
entrypoint: zrok-share.bash
depends_on:
zrok-enable:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt
environment:
HOME: /mnt
# internal configuration
STATE_DIRECTORY: /mnt # zrok homedir in container
# start share on reserved public frontend url
zrok-share:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
entrypoint:
- bash
- -euc
- |
if ! [[ -s ~/.zrok/reserved.json ]]; then
echo "ERROR: empty or missing reserved.json" >&2
exit 1
else
ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "$${ZROK_PUBLIC_URLS}" || "$${ZROK_PUBLIC_URLS}" == null ]]; then
echo "ERROR: frontend endpoints not defined" >&2
exit 1
else
echo "INFO: zrok public URLs: $${ZROK_PUBLIC_URLS}"
fi
ZROK_RESERVED_TOKEN=$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "$${ZROK_RESERVED_TOKEN}" && "$${ZROK_RESERVED_TOKEN}" == null ]]; then
echo "ERROR: zrok reservation token not defined" >&2
exit 1
else
echo "INFO: zrok reservation token: $${ZROK_RESERVED_TOKEN}"
fi
# most relevant options
ZROK_BACKEND_MODE: proxy # web, caddy, drive, proxy
ZROK_TARGET: http://zrok-test:9090 # backend target, is a path in container filesystem unless proxy mode
ZROK_INSECURE: # "--insecure" if proxy target has unverifiable TLS server certificate
ZROK_OAUTH_PROVIDER: # google, github
ZROK_OATH_EMAILS: # allow space-separated list of OAuth email addresses or @domain.tld
ZROK_BASIC_AUTH: # username:password, mutually-exclusive with ZROK_OAUTH_PROVIDER
echo "INFO: running: zrok $${@} $${ZROK_RESERVED_TOKEN}"
exec zrok "$${@}" $${ZROK_RESERVED_TOKEN}
fi
command: -- share reserved --headless
depends_on:
zrok-reserve:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt
ports:
- 127.0.0.1:2019:2019
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"
# least relevant options
ZROK_VERBOSE: # "--verbose"
ZROK_SHARE_OPTS: # additional arguments to "zrok reserve public" command
ZROK_FRONTENDS: # "public"
PFXLOG_NO_JSON: "true" # suppress JSON logging format
# demo server
zrok-test:

65
docker/compose/zrok-public-share/compose.yml
View File

@ -15,52 +15,47 @@ services:
depends_on:
zrok-init:
condition: service_completed_successfully
entrypoint:
- bash
- -euc
- |
if [[ -n "$(jq '.ziti_identity' ~/.zrok/environment.json 2>/dev/null)" ]]; then
echo "INFO: zrok environment is already enabled"
exit 0
else
zrok config set apiEndpoint ${ZROK_API_ENDPOINT:-https://api.zrok.io}
echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
exec zrok "$${@}"
fi
command: -- enable --headless --description "${ZROK_ENVIRONMENT_NAME:-docker temp public share}" ${ZROK_ENABLE_TOKEN}
entrypoint: zrok-enable.bash
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
STATE_DIRECTORY: /mnt
ZROK_ENABLE_TOKEN:
ZROK_API_ENDPOINT:
ZROK_ENVIRONMENT_NAME: docker-public-share
# start share on temporary public frontend url
# provision a temporary zrok frontend subdomain and start sharing the backend target
zrok-share:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
entrypoint:
- bash
- -euc
- |
set -o pipefail
ZROK_CMD="share public --headless"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
fi
if [[ -n "${ZROK_OAUTH_PROVIDER:-}" ]]; then
ZROK_CMD+=" --oauth-provider ${ZROK_OAUTH_PROVIDER}"
fi
ZROK_CMD+=" --backend-mode proxy ${ZROK_TARGET:-http://zrok-test:9090/}"
echo "INFO: running: zrok $${ZROK_CMD}"
exec zrok $${ZROK_CMD}
restart: no
entrypoint: zrok-share.bash
depends_on:
zrok-enable:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
ports: []
# - 127.0.0.1:2019:2019 # Caddy admin API
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"
# internal configuration
STATE_DIRECTORY: /mnt # zrok homedir in container
ZROK_FRONTEND_MODE: temp-public # tells zrok-share.bash to create a temporary subdomain and share until exit
# demo servers you can share with zrok
# most relevant options
ZROK_BACKEND_MODE: proxy # web, caddy, drive, proxy
ZROK_TARGET: http://zrok-test:9090 # backend target, is a path in container filesystem unless proxy mode
ZROK_INSECURE: # "--insecure" if proxy target has unverifiable TLS server certificate
ZROK_OAUTH_PROVIDER: # google, github
ZROK_OATH_EMAILS: # space-separated list of OAuth email addresses or @domain.tld to allow
ZROK_BASIC_AUTH: # username:password, mutually-exclusive with ZROK_OAUTH_PROVIDER
# least relevant options
ZROK_VERBOSE: # "--verbose"
ZROK_SHARE_OPTS: # additional arguments to "zrok share public" command
ZROK_FRONTENDS: # "public"
PFXLOG_NO_JSON: "true" # suppress JSON logging format
# demo server you can share with zrok
zrok-test:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
command: test endpoint --address 0.0.0.0 # 9090

12
docker/images/zrok/Dockerfile
View File

@ -1,5 +1,5 @@
# this builds docker.io/openziti/zrok
ARG ZITI_CLI_TAG="0.30.5"
ARG ZITI_CLI_TAG="0.31.0"
ARG ZITI_CLI_IMAGE="docker.io/openziti/ziti-cli"
# this builds docker.io/openziti/ziti-controller
FROM ${ZITI_CLI_IMAGE}:${ZITI_CLI_TAG}
@ -30,8 +30,14 @@ RUN mkdir -p -m0755 /licenses
COPY ./LICENSE /licenses/apache.txt
RUN mkdir -p /usr/local/bin
COPY ${ARTIFACTS_DIR}/${TARGETARCH}/${TARGETOS}/zrok /usr/local/bin/
RUN chmod 0755 /usr/local/bin/zrok
COPY ${ARTIFACTS_DIR}/${TARGETARCH}/${TARGETOS}/zrok \
./nfpm/zrok-enable.bash \
./nfpm/zrok-share.bash \
/usr/local/bin/
RUN chmod 0755 \
/usr/local/bin/zrok \
/usr/local/bin/zrok-enable.bash \
/usr/local/bin/zrok-share.bash
USER nobody
ENTRYPOINT [ "zrok" ]

8
docs/concepts/_category_.json Normal file
View File

@ -0,0 +1,8 @@
{
"label": "Concepts",
"position": 30,
"link": {
"type": "doc",
"id": "concepts/index"
}
}

6
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
@ -17,7 +18,8 @@ For example if you have a directory with a structure like this:
-rwxr-xr-x+ 1 Michael None 44250624 Apr 17 13:00 zrok.exe*
```
The files can be shared using a command such as:
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

3
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.
@ -9,4 +10,4 @@ sidebar_position: 25
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).
Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](../guides/self-hosting/self_hosting_guide.md).

7
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.
@ -15,9 +16,9 @@ The project also uses a very permissive license: Apache v2. We encourage people
## 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.
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!
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!

17
docs/downloads.md
View File

@ -1,17 +0,0 @@
---
sidebar_position: 100
---
# Downloads
Right now all `zrok` binaries are delivered from the release page at GitHub.
Head over to https://github.com/openziti/zrok/releases/latest to find the latest downloads.
You need the right download for your OS and CPU. This can be confusing because the OS, e.g., Raspberry Pi OS, could be 32bit even if you have a 64bit Pi (v3, 4, or Zero 2). Linux users can always find the right version by looking up the result of `uname -m` in this table.
| Result |Linux Download Name |
|------------------|--------------------|
| x86_64 |linux-amd64 |
| aarch64, arm/v8 |linux-arm64 |
| armhf, arm/v7 |linux-armv7 |

231
docs/getting-started.md → docs/getting-started.mdx
View File

@ -1,150 +1,77 @@
---
sidebar_position: 0
title: Getting Started with zrok
sidebar_label: Getting Started
sidebar_position: 10
---
# Getting Started with zrok
`zrok` is a next-generation sharing platform, designed to make sharing network and file resources simple and secure. `zrok` is a _Ziti Native Application_, built on top of the [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) programmable zero trust network overlay. `zrok` is open source, licensed under the Apache v2 license. You can choose to self-host `zrok` or leverage the free, managed offering provided by NetFoundry at https://zrok.io.
import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import styles from '@site/src/css/download-card.module.css';
As of version `v0.4.0`, `zrok` provides the ability to:
## What's a zrok?
* share resources [publicly](./concepts/sharing-public.md), similar to other distributed reverse proxies; this allows you to easily expose your private HTTP/S resources to the public internet without changing your network security
* share resources [privately](./concepts/sharing-private.md); private sharing uses peer-to-peer connectivity between two parties by leveraging the OpenZiti overlay. We believe the private sharing offered by `zrok` provides a unique level of security and privacy for this type of sharing.
`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.
As of version `v0.4.0`, `zrok` allows sharing these kinds of resources:
## Open Source
* HTTP/S resources; `zrok` provides reverse proxy capabilities for your HTTP/S endpoints, both publicly and privately
* file resources; `zrok` provides built in `web` capabilities, allowing you to share your files with other users, both publicly and privately
* TCP and UDP tunnels; `zrok` provides built-in `tunnel` capabilities, allowing you to share your TCP and UDP endpoints directly with other users privately (`zrok` does not currently offer public sharing of these kinds of resources)
`zrok` is licensed under Apache 2.0.
Let's take a look at how to get started with `zrok`.
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`!
:::note `zrok` moves fast!
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.
`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.
[Read more about zrok open source](/concepts/opensource.md).
:::
### Ziti native
## Downloading zrok
`zrok` is a _Ziti Native Application_, built on the [OpenZiti](https://openziti.io) platform, and supported by the OpenZiti community and NetFoundry team.
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 and you're not sure which download to use then check out the hints on [the Downloads page](./downloads.md).
## What's it for?
### Extract zrok Distribution
Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files.
Move the downloaded `zrok` distribution into a directory on your system. In my case, I've placed it in my home directory:
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.
```
$ ls -lF zrok*
-rwxr-xr-x 1 michael michael 14459159 May 31 13:46 zrok_0.4.0-rc6_linux_amd64.tar.gz*
```
If [sharing privately](./concepts/sharing-private.md), only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
Create a directory where the extracted distribution will sit:
## Installing the zrok Command
```
$ mkdir zrok
$ cd zrok/
```
Extract the `zrok` distribution:
```
$ tar zxvf ../zrok_0.4.0-rc1_linux_amd64.tar.gz
CHANGELOG.md
README.md
zrok
```
> NOTE: On Windows platforms the distribution is shipped as a `zip` archive. Windows Explorer includes support for extracting `zip` archives natively.
Add `zrok` to your shell's environment.
For Linux or macos:
```
$ export PATH=`pwd`:$PATH
```
For Windows (using Command Prompt):
```
> set PATH=%CD%;%PATH%
```
For Windows (using PowerShell):
```
$env:path += ";"+$pwd.Path
```
With the `zrok` executable in your path, you can then execute the `zrok` command from your shell:
```
$ ./zrok version
_
_____ __ ___ | | __
|_ / '__/ _ \| |/ /
/ /| | | (_) | <
/___|_| \___/|_|\_\
v0.4.0-rc6 [c889005]
```
## 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:
```
$ zrok config set apiEndpoint https://zrok.mydomain.com
[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_.
```
$ zrok status
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.
<AssetsProvider>
<div className={styles.downloadContainer}>
<DownloadCard
osName="Windows"
osLogo="/img/logo-windows.svg"
infoText="Binary executable"
guideLink="/docs/guides/install/windows"
/>
<DownloadCard
osName="macOS"
osLogo="/img/logo-apple.svg"
infoText="Binary executable"
guideLink="/docs/guides/install/macos"
/>
<DownloadCard
osName="Linux"
osLogo="/img/logo-linux.svg"
infoText="DEB, RPM packages"
guideLink="/docs/guides/install/linux"
/>
</div>
</AssetsProvider>
## 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
```
$ zrok invite
```buttonless title="Output"
enter and confirm your email address...
> user@domain.com
@ -155,30 +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:
```
$ zrok invite
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)
@ -206,23 +116,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
@ -273,21 +185,22 @@ 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`:
```text
zrok share public
```
$ zrok share public
```buttonless title="Output"
Error: accepts 1 arg(s), received 0
Usage:
zrok share public <target> [flags]
@ -338,13 +251,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 +283,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 +301,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
```
@ -398,13 +311,13 @@ $ 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.
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
```
@ -415,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
@ -431,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_.
@ -441,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"

2
docs/guides/_category_.json
View File

@ -1,6 +1,6 @@
{
"label": "Guides",
"position": 30,
"position": 50,
"link": {
"type": "generated-index"
}

127
docs/guides/_frontdoor-docker.mdx Normal file
View File

@ -0,0 +1,127 @@
## Goal
Proxy a reserved public subdomain to a backend target with an always-on Docker Compose service.
## How it Works
The Docker Compose project uses your zrok account token to reserve a public subdomain and keep sharing the backend
target.
When the project runs it will:
1. enable a zrok environment unless `/mnt/.zrok/environment.json` exists in the `zrok_env` volume
1. reserve a public subdomain for the service unless `/mnt/.zrok/reserved.json` exists
1. start sharing the target specified in the `ZROK_TARGET` environment variable
## Create the Docker Project
1. Make a folder on your computer to use as a Docker Compose project for your zrok public share with a reserved subdomain and switch to the new directory in your terminal.
1. Download [the reserved public share `compose.yml` project file](pathname:///zrok-public-reserved/compose.yml) into the same directory.
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. Be sure to `--detach` so the project runs in the background if you want it to auto-restart when your computer reboots.
```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 appear in the graph.
```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 existing HTTP 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 URL.
```bash title=".env"
ZROK_TARGET="http://example.com:8080"
```
```bash
docker compose down && docker compose up
```
## Require Authentication
You can require a password or an OAuth login with certain email addresses.
### OAuth Email
You can allow specific email addresses or an email domain by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` and
`ZROK_SHARE_OPTS` to specify additional command-line options to `zrok reserve public`. Read more about the OAuth
features in [this blog post](https://blog.openziti.io/the-zrok-oauth-public-frontend).
```bash title=".env"
ZROK_OAUTH_PROVIDER="github"
ZROK_SHARE_OPTS="--oauth-email-domains @example.com"
```
## Caddy is Powerful
The reserved public share project uses zrok's default backend mode, `proxy`. Another backend mode, `caddy`, accepts a path to [a Caddyfile](https://caddyserver.com/docs/caddyfile) as the value of `ZROK_TARGET` ([zrok Caddyfile examples](https://github.com/openziti/zrok/tree/main/etc/caddy)).
Caddy is the most powerful and flexible backend mode in zrok. You must reserve a new public subdomain whenever you switch the backend mode, so using `caddy` reduces the risk that you'll have to share a new frontend URL with your users.
With Caddy, you can balance the workload for websites or web services or share static sites and files or all of the above at the same time. You can update the Caddyfile and restart the Docker Compose project to start sharing the new configuration with the same reserved public subdomain.
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 load balancing, and mounts the Caddyfile into the container.
```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. Start a new Docker Compose project or delete the existing state volume.
```bash
docker compose down --volumes
```
If you prefer to keep using the same zrok environment with the new share then delete `/mnt/.zrok/reserved.json` instead of the entire volume.
1. Run the project to load the new configuration.
```bash
docker compose up --detach
```
1. Note the new reserved share URL from the log.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
```

190
docs/guides/_frontdoor-linux.mdx Normal file
View File

@ -0,0 +1,190 @@
import AnsibleRepoSetup from './install/_ansible_repo_setup.yaml'
import ConcatenateYamlSnippets from '@site/src/components/cat-yaml.jsx'
## Goal
Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
## How it Works
The `zrok-share` package creates a `zrok-share.service` unit in systemd. The administrator edits the service's configuration file to specify the:
1. zrok environment enable token
1. target URL or files to be shared and backend mode, e.g. `proxy`
1. authentication options, if wanted
When the service starts it will:
1. enable the zrok environment unless `/var/lib/zrok-share/.zrok/environment.json` exists
1. reserve a public subdomain for the service unless `/var/lib/zrok-share/.zrok/reserved.json` exists
1. start sharing the target specified as `ZROK_TARGET` in the environment file
## Installation
1. Set up `zrok`'s Linux package repository by following [the Linux install guide](/guides/install/linux.mdx#install-zrok-from-the-repository), or run this one-liner to complete the repo setup and install packages.
```bash
curl -sSLf https://get.openziti.io/install.bash \
| sudo bash -s zrok-share
```
1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
```bash title="Ubuntu, Debian"
sudo sudo apt install zrok-share
```
```bash title="Fedora, Rocky"
sudo dnf install zrok-share
```
<Details>
<summary>Ansible Playbook</summary>
<ConcatenateYamlSnippets
title="Set up package repository and install zrok-share"
>
{AnsibleRepoSetup}
{`
- name: Install zrok-share package
gather_facts: false
hosts: all
become: true
tasks:
- name: Install zrok-share
ansible.builtin.package:
name: zrok-share
state: present
- name: Copy env config from Ansible controller to target
copy:
dest: /opt/openziti/etc/zrok/zrok-share.env
src: /opt/openziti/etc/zrok/zrok-share.env
- name: Enable and restart service
systemd:
name: zrok-share
enabled: yes
state: restarted
daemon_reload: yes
- name: Wait for service
systemd:
name: zrok-share
state: started
register: service_status
until: service_status.status.ActiveState == 'active'
retries: 30
delay: 1
`}
</ConcatenateYamlSnippets>
</Details>
## Enable
Save the enable token from the zrok console in the configuration file.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_ENABLE_TOKEN="14cbfca9772f"
```
## Use Cases
You may change the target for the current backend mode, e.g. `proxy`, by editing the configuration file and restarting the service. The reserved subdomain will remain the same.
You may switch between backend modes or change authentication options by deleting `/var/lib/zrok-share/.zrok/reserved.json` and restarting the service. A new subdomain will be reserved.
### Proxy a Web Server
Proxy a reserved subdomain to an existing web server. The web server could be on a private network or on the same host as zrok.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="http://127.0.0.1:3000"
ZROK_BACKEND_MODE="proxy"
```
If your HTTPS server has an unverifiable TLS server certificate then you must set `--insecure`.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_INSECURE="--insecure"
```
### Serve Static Files
Run zrok's embedded web server to serve the files in a directory. If there's an `index.html` file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the files. The directory must be readable by 'other', e.g. `chmod -R o+rX /var/www/html`.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/var/www/html"
ZROK_BACKEND_MODE="web"
```
### Caddy Server
Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile is available in the path shown.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/opt/openziti/etc/zrok/multiple_upstream.Caddyfile"
ZROK_BACKEND_MODE="caddy"
```
### Network Drive
This uses zrok's `drive` backend mode to serve a directory of static files as a virtual network drive. The directory must be readable by 'other', e.g. `chmod -R o+rX /usr/share/doc`.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_TARGET="/usr/share/doc"
ZROK_BACKEND_MODE="drive"
```
[Learn more about this feature in this blog post](https://blog.openziti.io/zrok-drives-an-early-preview).
## Authentication
You can limit access to certain email addresses with OAuth or require a password.
### OAuth
You can require that visitors authenticate with an email address that matches at least one of the suffixes you specify. Add the following to the configuration file.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_OAUTH_PROVIDER="github" # or google
ZROK_OAUTH_EMAILS="bob@example.com @acme.example.com"
```
### Password
Enable HTTP basic authentication by adding the following to the configuration file.
```bash title="/opt/openziti/etc/zrok/zrok-share.env"
ZROK_BASIC_AUTH="user:passwd"
```
## Start the Service
Start the service, and check the zrok console or the service log for the reserved subdomain.
```bash title="run now and at startup"
sudo systemctl enable --now zrok-share.service
```
```bash title="run now"
sudo systemctl restart zrok-share.service
```
```bash
journalctl -u zrok-share.service
```
## Compatibility
The Linux distribution must have a package manager that understands the `.deb` or `.rpm` format and be running systemd v232 or newer. The service was tested with:
* Ubuntu 20.04, 22.04, 23.04
* Debian 11 12
* Rocky 8, 9
* Fedora 37, 38
## Package Contents
The files included in the `zrok-share` package are sourced [here in GitHub](https://github.com/openziti/zrok/tree/main/nfpm).

8
docs/guides/docker-share/docker_private_share_guide.md
View File

@ -8,6 +8,8 @@ sidebar_label: Private Share
With zrok, you can privately share a server app that's running in Docker, or any server that's reachable by the zrok container. Then, a zrok private access running somewhere else can use the private share. In this guide we'll cover both sides: the private share and the private access.
Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.md).
## Walkthrough Video
<iframe width="100%" height="315" src="https://www.youtube.com/embed/HxyvtFAvwUE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
@ -18,7 +20,7 @@ To follow this guide you will need [Docker](https://docs.docker.com/get-docker/)
If you have installed Docker Desktop on macOS or Windows then you are all set.
## Private Share with Docker Compose
## Begin Sharing Privately with zrok in Docker
First, let's create the private share.
@ -53,9 +55,9 @@ First, let's create the private share.
Keep track of this token so you can use it in your zrok private access project.
## Private Access with Docker Compose
## Access the Private Share
Now that we have a private share we can access it with zrok running in Docker. Next, let's access the demo web server in a web browser.
Now that we have a private share we can access it with the zrok command or by running a separate Docker Compose project.
1. Make a folder on your computer to use as a Docker Compose project for your zrok private access.
1. In your terminal, change directory to your newly-created project folder.

67
docs/guides/docker-share/docker_public_share_guide.md
View File

@ -1,11 +1,12 @@
---
title: Docker Public Share
sidebar_position: 10
sidebar_label: Public Share
---
# Docker Public Share
With zrok and Docker, you can publicly share a web server that's running in a local container or anywhere that's reachable by the zrok container. The share can be reached through a temporary public URL that expires when the container is stopped. If you're looking for a reserved subdomain for the share, check out [zrok frontdoor](/guides/frontdoor.mdx).
With zrok and Docker, you can publicly share a web server that's running in a local container or anywhere that's reachable by the zrok container. The share can be reached through a public URL thats temporary or reserved (reusable).
Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.md).
## Walkthrough Video
@ -15,13 +16,13 @@ With zrok and Docker, you can publicly share a web server that's running in a lo
To follow this guide you will need [Docker](https://docs.docker.com/get-docker/) and [the Docker Compose plugin](https://docs.docker.com/compose/install/) for running `docker compose` commands in your terminal.
## Temporary or Reserved Public Share
## Begin Sharing with Docker Compose
A temporary public share is a great way to share a web server running in a container with someone else for a short time. A reserved public share is a great way to share a reliable web server running in a container with someone else for a long time.
A temporary public share is a great way to share a web server running in a container with someone else for a short time.
1. Make a folder on your computer to use as a Docker Compose project for your zrok public share.
1. In your terminal, change directory to the newly-created project folder.
1. Download either [the temporary public share project file](pathname:///zrok-public-share/compose.yml) or [the reserved public share project file](pathname:///zrok-public-reserved/compose.yml) into the project folder.
1. Download [the temporary public share project file](pathname:///zrok-public-share/compose.yml).
1. Copy your zrok environment 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"
@ -54,7 +55,7 @@ This concludes sharing the demo web server. Read on to learn how to pivot to sha
## 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.
The simplest way to share your web server is to set `ZROK_TARGET` (e.g. `https://example.com`) in the environment file.
```bash title=".env"
ZROK_TARGET="http://example.com:8080"
@ -62,7 +63,7 @@ ZROK_TARGET="http://example.com:8080"
## 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.
You can require authentication for your public share by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` with zrok.io. You could parse the authenticated email address from the request cookie if you're building a custom server app. Read more about the OAuth features in [this blog post](https://blog.openziti.io/the-zrok-oauth-public-frontend).
```bash title=".env"
ZROK_OAUTH_PROVIDER="github"
@ -70,6 +71,12 @@ ZROK_OAUTH_PROVIDER="github"
## Customize Temporary Public Share
This technique is useful for adding a containerized service to the project, or mounting a filesystem directory into the container to share as a static website or file server.
Any additional services specified in the override file will be merged with `compose.yml` when you `up` the project.
You may override individual values from in `compose.yml` by specifying them in the override file.
1. Create a file `compose.override.yml`. This example demonstrates sharing a static HTML directory `/tmp/html` from the Docker host's filesystem.
```yaml title="compose.override.yml"
@ -96,52 +103,6 @@ ZROK_OAUTH_PROVIDER="github"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```
## Customize Reserved Public Share
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/
```
## Destroy the zrok Environment
This destroys the Docker volumes containing the zrok environment secrets. The zrok environment can also be destroyed in the web console.

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

@ -0,0 +1,56 @@
---
title: zrok frontdoor
sidebar_label: frontdoor
sidebar_position: 20
hide_table_of_contents: true
---
import OsTabs from '@theme/OsTabs';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
// import Details from '@theme/MDXComponents/Details';
import LinuxService from './_frontdoor-linux.mdx';
import ReservedDocker from './_frontdoor-docker.mdx';
**zrok frontdoor** provides a shielded entry point for your production website or service. This is useful if you want to expose it to the public internet, but not 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 natively as a system service provided by the `zrok-share` DEB or RPM package.
If you'd prefer to run zrok in Docker instead of installing the package then you can follow the Docker instructions. With Docker, the steps are the same for Linux, [macOS](./?os=Mac+OS), and [Windows](./?os=Windows).
<LinuxService/>
</TabItem>
<TabItem value="Mac OS">
On macOS, zrok frontdoor is implemented as a Docker Compose 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 Compose project which reserves a public subdomain for your website or service.
<ReservedDocker/>
</TabItem>
</OsTabs>
## Concepts
Overview of [zrok reserved shares](/concepts/sharing-reserved.md)

55
docs/guides/install/_ansible_repo_setup.yaml Normal file
View File

@ -0,0 +1,55 @@
- name: Set up zrok Package Repo
gather_facts: true
hosts: all
become: true
tasks:
- name: Set up apt repo
when: ansible_os_family == "Debian"
block:
- name: Install playbook dependencies
ansible.builtin.package:
name:
- gnupg
state: present
- name: Fetch armored pubkey
ansible.builtin.uri:
url: https://get.openziti.io/tun/package-repos.gpg
return_content: yes
register: armored_pubkey
- name: Dearmor pubkey
ansible.builtin.shell: |
gpg --dearmor --output /usr/share/keyrings/openziti.gpg <<< "{{ armored_pubkey.content }}"
args:
creates: /usr/share/keyrings/openziti.gpg
executable: /bin/bash
- name: Set pubkey filemode
ansible.builtin.file:
path: /usr/share/keyrings/openziti.gpg
mode: 'a+rX'
- name: Install OpenZiti repo deb source
ansible.builtin.copy:
dest: /etc/apt/sources.list.d/openziti-release.list
content: |
deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable debian main
- name: Refresh Repo Sources
ansible.builtin.apt:
update_cache: yes
cache_valid_time: 3600
- name: Set up yum repo
when: ansible_os_family == "RedHat"
block:
- name: Install OpenZiti repo rpm source
ansible.builtin.yum_repository:
name: OpenZitiRelease
description: OpenZiti Release
baseurl: https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch
enabled: yes
gpgkey: https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch/repodata/repomd.xml.key
repo_gpgcheck: yes
gpgcheck: no

8
docs/guides/install/_category_.json Normal file
View File

@ -0,0 +1,8 @@
{
"label": "Install",
"position": 10,
"link": {
"type": "doc",
"id": "guides/install/index"
}
}

31
docs/guides/install/index.mdx Normal file
View File

@ -0,0 +1,31 @@
---
title: Install
---
import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import styles from '@site/src/css/download-card.module.css';
<AssetsProvider>
<div className={styles.downloadContainer}>
<DownloadCard
osName="Windows"
osLogo="/img/logo-windows.svg"
infoText="Binary executable"
guideLink="/docs/guides/install/windows"
/>
<DownloadCard
osName="macOS"
osLogo="/img/logo-apple.svg"
infoText="Binary executable"
guideLink="/docs/guides/install/macos"
/>
<DownloadCard
osName="Linux"
osLogo="/img/logo-linux.svg"
infoText="DEB, RPM packages"
guideLink="/docs/guides/install/linux"
/>
</div>
</AssetsProvider>

195
docs/guides/install/linux.mdx Normal file
View File

@ -0,0 +1,195 @@
---
title: Install zrok in Linux
sidebar_label: Linux
---
import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import styles from '@site/src/css/download-card.module.css';
import AnsibleRepoSetup from './_ansible_repo_setup.yaml'
import ConcatenateYamlSnippets from '@site/src/components/cat-yaml.jsx'
## Linux Binary
<AssetsProvider>
<div className={styles.downloadContainer}>
<DownloadCard
osName="Linux"
osLogo="/img/logo-linux.svg"
/>
</div>
</AssetsProvider>
Download the binary distribution for your Linux distribution's architecture or run the install script below to pick the correct CPU architecture automatically. For Intel and AMD 64-bit machines use the `amd64` distribution. For Raspberry Pi use the `arm64` distribution.
<Details>
<summary>Manually install in `~/bin/zrok`</summary>
1. Unarchive the distribution in a temporary directory.
```text
mkdir /tmp/zrok && tar -xf ./zrok*linux*.tar.gz -C /tmp/zrok
```
1. Install the `zrok` executable.
```text
mkdir -p ~/bin && install /tmp/zrok/zrok ~/bin/
```
1. Add `~/bin` to your shell's executable search path. Optionally add this to your ~/.zshenv to persist the change.
```text
PATH=~/bin:$PATH
```
1. With the `zrok` executable in your path, you can then execute the `zrok` command from your shell:
```text
zrok version
```
```buttonless title="Output"
_
_____ __ ___ | | __
|_ / '__/ _ \| |/ /
/ /| | | (_) | <
/___|_| \___/|_|\_\
v0.4.0 [c889005]
```
</Details>
<Details>
<summary>Script to install binary in `/usr/local/bin/zrok`</summary>
This script auto-selects the correct architecture, and may be helpful for Raspberry Pi users.
```text
(set -euo pipefail;
cd $(mktemp -d);
ZROK_VERSION=$(
curl -sSf https://api.github.com/repos/openziti/zrok/releases/latest \
| jq -r '.tag_name'
);
case $(uname -m) in
x86_64) GOXARCH=amd64 ;;
aarch64|arm64) GOXARCH=arm64 ;;
armv7|armhf|arm) GOXARCH=arm ;;
*) echo "ERROR: unknown arch '$(uname -m)'" >&2
exit 1 ;;
esac;
curl -sSfL \
"https://github.com/openziti/zrok/releases/download/${ZROK_VERSION}/zrok_${ZROK_VERSION#v}_linux_${GOXARCH}.tar.gz" \
| tar -xz -f -;
sudo install -o root -g root ./zrok /usr/local/bin/;
zrok version;
)
```
</Details>
## Install `zrok` from the Repository
We recommend that you install `zrok` from the Linux package repository with the manual steps or the setup script. DEB and RPM packages are available for amd64, arm64, and armv7 architectures.
:::info
Check out [zrok frontdoor](/guides/frontdoor.mdx?os=Linux) for running `zrok` as an always-on service.
:::
<Details>
<summary>Manually set up DEB repository</summary>
```text
(set -euo pipefail;
curl -sSLf https://get.openziti.io/tun/package-repos.gpg \
| sudo gpg --dearmor --output /usr/share/keyrings/openziti.gpg;
sudo chmod a+r /usr/share/keyrings/openziti.gpg;
sudo tee /etc/apt/sources.list.d/openziti-release.list >/dev/null <<EOF;
deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable debian main
EOF
sudo apt update;
sudo apt install zrok;
zrok version;
)
```
</Details>
<Details>
<summary>Manually set up RPM repository</summary>
```text
(set -euo pipefail;
sudo tee /etc/yum.repos.d/openziti-release.repo >/dev/null <<\EOF;
[OpenZitiRelease]
name=OpenZiti Release
baseurl=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch
enabled=1
gpgcheck=0
gpgkey=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat/$basearch/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
sudo dnf update;
sudo dnf install zrok;
zrok version;
)
```
</Details>
<Details>
<summary>Script to set up DEB or RPM repository</summary>
1. Download the zrok install script.
```text
curl -sSLfo ./zrok-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 ./zrok-install.bash
```
1. Run the script as root to add the package repo and install the `zrok` package.
```text
sudo bash ./zrok-install.bash zrok
```
</Details>
<Details>
<summary>Ansible Playbook</summary>
<ConcatenateYamlSnippets
title="Set up package repository and install zrok">
{AnsibleRepoSetup}
{`
- name: Install zrok package
gather_facts: false
hosts: all
become: true
tasks:
- name: Install zrok
ansible.builtin.package:
name: zrok
state: present
`}
</ConcatenateYamlSnippets>
</Details>

55
docs/guides/install/macos.mdx Normal file
View File

@ -0,0 +1,55 @@
---
title: Install zrok in macOS
sidebar_label: macOS
---
import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import styles from '@site/src/css/download-card.module.css';
## Darwin Binary
<AssetsProvider>
<div className={styles.downloadContainer}>
<DownloadCard
osName="macOS"
osLogo="/img/logo-apple.svg"
/>
</div>
</AssetsProvider>
Download the binary distribution for your macOS architecture. For Intel Macs use the `amd64` distribution. For Apple Silicon Macs use the `arm64` distribution.
1. Unarchive the distribution in a temporary directory.
```text
mkdir /tmp/zrok && tar -xf ./zrok*darwin*.tar.gz -C /tmp/zrok
```
1. Install the `zrok` executable.
```text
mkdir -p ~/bin && install /tmp/zrok/zrok ~/bin/
```
1. Add `~/bin` to your shell's executable search path. Optionally add this to your ~/.zshenv to persist the change.
```text
PATH=~/bin:$PATH
```
1. With the `zrok` executable in your path, you can then execute the `zrok` command from your shell:
```text
zrok version
```
```buttonless title="Output"
_
_____ __ ___ | | __
|_ / '__/ _ \| |/ /
/ /| | | (_) | <
/___|_| \___/|_|\_\
v0.4.0 [c889005]
```

52
docs/guides/install/windows.mdx Normal file
View File

@ -0,0 +1,52 @@
---
title: Install zrok in Windows
sidebar_label: Windows
---
import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import styles from '@site/src/css/download-card.module.css';
## Windows Binary
<AssetsProvider>
<div className={styles.downloadContainer}>
<DownloadCard
osName="Windows"
osLogo="/img/logo-windows.svg"
/>
</div>
</AssetsProvider>
1. Unarchive the distribution in a temporary directory:
```text
New-Item -Path "$env:TEMP\zrok" -ItemType Directory -ErrorAction Stop
tar -xf .\zrok*windows*.tar.gz -C "$env:TEMP\zrok"
```
1. Install the `zrok` executable and include HOME\bin in the search PATH.
```text
$source = Join-Path -Path $env:TEMP -ChildPath "zrok\zrok.exe"
$destination = Join-Path -Path $env:HOME -ChildPath "bin\zrok.exe"
New-Item -Path $destination -ItemType Directory -ErrorAction SilentlyContinue
Copy-Item -Path $source -Destination $destination
$env:path += ";"+$destination
```
1. With the `zrok` executable in your path, you can then execute the `zrok` directly.
```text
zrok version
```
```buttonless title="Output"
_____ __ ___ | | __
|_ / '__/ _ \| |/ /
/ /| | | (_) | <
/___|_| \___/|_|\_\
v0.4.0 [c889005]
```

2
docs/guides/self-hosting/_category_.json
View File

@ -1,6 +1,6 @@
{
"label": "Self Hosting",
"position": 20,
"position": 80,
"link": {
"type": "generated-index"
}

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

2
nfpm/README.md
View File

@ -1,4 +1,4 @@
# nfpm supporting files
These files are sourced by nfpm when invoked by goreleaser to build Linux packages.
These files are sourced by nfpm when invoked by goreleaser to build Linux packages, and by BuildKit when building the Docker images.

6
nfpm/zrok-enable.bash
View File

@ -8,7 +8,7 @@ set -o nounset
set -o pipefail
BASENAME=$(basename "$0")
DEFAULT_ZROK_ENVIRONMENT_NAME="zrok-share.service on $(hostname -s)"
DEFAULT_ZROK_ENVIRONMENT_NAME="zrok-share service on $(hostname -s 2>/dev/null || echo localhost)"
if (( $# )); then
case $1 in
@ -38,14 +38,14 @@ fi
if (( $# )); then
if [[ -s "$1" ]]; then
echo "INFO: reading enable parameters from $1"
source "$1"
else
echo "ERROR: \$1="$1" is empty or not a readable file" >&2
exit 1
fi
else
echo "ERROR: need filename argument to read environment configuration" >&2
exit 1
echo "INFO: reading enable parameters from environment variables"
fi
if [[ -z "${ZROK_ENABLE_TOKEN}" ]]; then

194
nfpm/zrok-share.bash
View File

@ -7,17 +7,29 @@ set -o errexit
set -o nounset
set -o pipefail
share_reserved(){
local token="$1"
local target="$2"
shift 2
local opts="${*:-}"
local zrok_cmd="share reserved ${token} --headless ${opts} --override-endpoint ${target}"
echo "INFO: running: zrok ${zrok_cmd}"
exec zrok ${zrok_cmd}
}
if ! command -v jq &>/dev/null; then
echo "ERROR: jq is needed but not installed" >&2
exit 1
fi
# set HOME to the first colon-sep dir in STATE_DIRECTORY inherited from systemd, e.g. /var/lib/zrok-share
export HOME="${STATE_DIRECTORY%:*}"
# set HOME to the first colon-sep dir in STATE_DIRECTORY inherited from systemd (/var/lib/zrok-share) or docker (/mnt)
export HOME="${STATE_DIRECTORY%:*}"
if (( $# )); then
if [[ -s "$1" ]]; then
echo "INFO: reading share configuration from $1"
source "$1"
shift
else
echo "ERROR: '$1' is empty or not readable" >&2
exit 1
@ -30,104 +42,118 @@ else
# echo "ERROR: need /opt/openziti/etc/zrok.env or filename argument to read share configuration" >&2
# exit 1
# fi
echo "ERROR: need filename argument to read share configuration" >&2
exit 1
echo "INFO: reading share configuration from environment variables"
fi
if [[ -s ~/.zrok/reserved.json ]]; then
ZROK_RESERVED_TOKEN="$(jq '.token' ~/.zrok/reserved.json 2>/dev/null)"
[[ -n "${ZROK_TARGET:-}" ]] || {
echo "ERROR: ZROK_TARGET is not defined." >&2
exit 1
}
# default mode is reserved (public), override mode is temp-public, i.e., "share public" without a reserved subdomain
if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
ZROK_CMD="share public --headless ${ZROK_VERBOSE:-}"
elif [[ -s ~/.zrok/reserved.json ]]; then
ZROK_RESERVED_TOKEN="$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)"
if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
echo "ERROR: invalid reserved.json: '$(jq -c . ~/.zrok/reserved.json)'" >&2
exit 1
else
echo "INFO: zrok backend is already reserved: ${ZROK_RESERVED_TOKEN}"
ZITI_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
ZITI_CMD+=" ${ZROK_VERBOSE:-} ${ZROK_INSECURE:-}"
share_reserved ${ZITI_CMD}
fi
else
ZROK_CMD="reserve public --json-output ${ZROK_VERBOSE:-}"
[[ -n "${ZROK_TARGET:-}" ]] || {
echo "ERROR: ZROK_TARGET was not defined in /opt/openziti/etc/zrok/zrok-share.env." >&2
exit 1
}
[[ -n "${ZROK_BACKEND_MODE:-}" ]] || {
echo "WARNING: ZROK_BACKEND_MODE was not defined, assuming mode 'proxy'." >&2
ZROK_BACKEND_MODE="proxy"
}
case "${ZROK_BACKEND_MODE}" in
proxy)
if ! [[ "${ZROK_TARGET}" =~ ^https?:// ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an HTTP URL" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
caddy)
if ! [[ "${ZROK_TARGET}" =~ ^/ ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an absolute filesystem path." >&2
exit 1
elif ! [[ -f "${ZROK_TARGET}" && -r "${ZROK_TARGET}" ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not a readable regular file" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
web|drive)
if ! [[ "${ZROK_TARGET}" =~ ^/ ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an absolute filesystem path." >&2
exit 1
elif ! [[ -d "${ZROK_TARGET}" && -r "${ZROK_TARGET}" ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not a readable directory" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
*)
echo "WARNING: ZROK_BACKEND_MODE='${ZROK_BACKEND_MODE}' is not a recognized mode for a zrok public share."\
" ZROK_TARGET value will not validated before running." >&2
;;
esac
ZROK_CMD+=" --backend-mode ${ZROK_BACKEND_MODE} ${ZROK_TARGET}"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
fi
if [[ -n "${ZROK_OAUTH_PROVIDER:-}" ]]; then
ZROK_CMD+=" --oauth-provider ${ZROK_OAUTH_PROVIDER}"
fi
fi
[[ -n "${ZROK_BACKEND_MODE:-}" ]] || {
echo "WARNING: ZROK_BACKEND_MODE was not defined, assuming mode 'proxy'." >&2
ZROK_BACKEND_MODE="proxy"
}
case "${ZROK_BACKEND_MODE}" in
proxy)
if ! [[ "${ZROK_TARGET}" =~ ^https?:// ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an HTTP URL" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
caddy)
if ! [[ "${ZROK_TARGET}" =~ ^/ ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an absolute filesystem path." >&2
exit 1
elif ! [[ -f "${ZROK_TARGET}" && -r "${ZROK_TARGET}" ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not a readable regular file" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
web|drive)
if ! [[ "${ZROK_TARGET}" =~ ^/ ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not an absolute filesystem path." >&2
exit 1
elif ! [[ -d "${ZROK_TARGET}" && -r "${ZROK_TARGET}" ]]; then
echo "ERROR: ZROK_TARGET='${ZROK_TARGET}' is not a readable directory" >&2
exit 1
else
echo "INFO: validated backend mode ${ZROK_BACKEND_MODE} and target ${ZROK_TARGET}"
fi
;;
*)
echo "WARNING: ZROK_BACKEND_MODE='${ZROK_BACKEND_MODE}' is not a recognized mode for a zrok public share."\
" ZROK_TARGET value will not validated before running." >&2
;;
esac
ZROK_CMD+=" --backend-mode ${ZROK_BACKEND_MODE} ${ZROK_TARGET}"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
fi
if [[ -n "${ZROK_OAUTH_PROVIDER:-}" ]]; then
ZROK_CMD+=" --oauth-provider ${ZROK_OAUTH_PROVIDER}"
if [[ -n "${ZROK_OAUTH_EMAILS:-}" ]]; then
for EMAIL in ${ZROK_OAUTH_EMAILS}; do
if ! [[ ${EMAIL} =~ @ ]]; then
echo "WARNING: '${EMAIL}' does not contain '@' so it may match more than one email domain!" >&2
fi
ZROK_CMD+=" --oauth-email-domains ${EMAIL}"
done
fi
echo "INFO: running: zrok ${ZROK_CMD}"
zrok ${ZROK_CMD} | jq -rc | tee ~/.zrok/reserved.json
elif [[ -n "${ZROK_BASIC_AUTH:-}" ]]; then
ZROK_CMD+=" --basic-auth ${ZROK_BASIC_AUTH}"
fi
if ! [[ -s ~/.zrok/reserved.json ]]; then
echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&2
exit 1
else
ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "${ZROK_PUBLIC_URLS}" || "${ZROK_PUBLIC_URLS}" == null ]]; then
echo "ERROR: frontend endpoints not defined in $(realpath ~/.zrok)/reserved.json" >&2
exit 1
else
echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
fi
ZROK_RESERVED_TOKEN=$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
echo "ERROR: zrok reservation token not defined in $(realpath ~/.zrok)/reserved.json" >&2
exit 1
fi
ZROK_CMD="share reserved ${ZROK_RESERVED_TOKEN} --headless --override-endpoint ${ZROK_TARGET}"
ZROK_CMD+=" ${ZROK_VERBOSE:-} ${ZROK_INSECURE:-}"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
fi
echo "INFO: running: zrok ${ZROK_CMD}"
echo "INFO: running: zrok ${ZROK_CMD}"
if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
# share until exit
exec zrok ${ZROK_CMD}
else
# reserve and continue
zrok ${ZROK_CMD} | jq -rc | tee ~/.zrok/reserved.json
# share the reserved backend target until exit
if ! [[ -s ~/.zrok/reserved.json ]]; then
echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&2
exit 1
else
ZROK_PUBLIC_URLS=$(jq -cr '.frontend_endpoints' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "${ZROK_PUBLIC_URLS}" || "${ZROK_PUBLIC_URLS}" == null ]]; then
echo "ERROR: frontend endpoints not defined in $(realpath ~/.zrok)/reserved.json" >&2
exit 1
else
echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
fi
ZROK_RESERVED_TOKEN=$(jq -r '.token' ~/.zrok/reserved.json 2>/dev/null)
if [[ -z "${ZROK_RESERVED_TOKEN}" || "${ZROK_RESERVED_TOKEN}" == null ]]; then
echo "ERROR: zrok reservation token not defined in $(realpath ~/.zrok)/reserved.json" >&2
exit 1
fi
ZROK_CMD="${ZROK_RESERVED_TOKEN} ${ZROK_TARGET}"
ZROK_CMD+=" ${ZROK_VERBOSE:-} ${ZROK_INSECURE:-}"
share_reserved ${ZROK_CMD}
fi
fi

5
nfpm/zrok-share.env
View File

@ -73,6 +73,11 @@ ZROK_SHARE_OPTS=""
# WARNING: changing this value requires provisioning a new frontend URL
#ZROK_OAUTH_EMAILS="bob@acme.example.com alice@forge.example.com @corp.example.com"
# you MAY require a password with HTTP basic authentication
# WARNING: changing this value requires provisioning a new frontend URL
# NOTE: basic auth and oauth are mutually exclusive
#ZROK_BASIC_AUTH=""
# set if self-hosting zrok and not using only the default frontend name 'public'; must be a space-separated list
# WARNING: changing this value requires provisioning a new frontend URL
#ZROK_FRONTENDS="public"

1
website/.nvmrc Normal file
View File

@ -0,0 +1 @@
v18.18.2

33
website/docusaurus.config.js
View File

@ -44,7 +44,24 @@ const config = {
}
]
}
]
],
function myPlugin(context, options) {
return {
name: 'custom-webpack-plugin',
configureWebpack(config, isServer, utils) {
return {
module: {
rules: [
{
test: /\.yaml$/,
use: 'yaml-loader',
},
],
},
};
},
};
},
],
presets: [
@ -95,25 +112,13 @@ const config = {
type: 'doc',
docId: 'getting-started',
position: 'right',
label: 'What is zrok?',
label: 'Docs',
},
{
href: 'https://github.com/orgs/openziti/projects/16',
label: 'Roadmap',
position: 'right',
},
{
type: 'doc',
docId: 'getting-started',
position: 'right',
label: 'Docs',
},
{
type: 'doc',
docId: 'downloads',
position: 'right',
label: 'Downloads',
},
{
href: 'https://github.com/openziti/zrok',
label: 'GitHub',

11781
website/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

16
website/package.json
View File

@ -14,18 +14,20 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "^2.4.3",
"@docusaurus/plugin-client-redirects": "^2.4.3",
"@docusaurus/preset-classic": "^2.4.3",
"@mdx-js/react": "^1.6.22",
"@docusaurus/core": "^3.0.0",
"@docusaurus/plugin-client-redirects": "^3.0.0",
"@docusaurus/preset-classic": "^3.0.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^1.2.1",
"prism-react-renderer": "^1.3.5",
"react": "^17.0.2",
"react-dom": "^17.0.2",
"react": "^18.2.0",
"react-device-detect": "^2.2.3",
"react-dom": "^18.2.0",
"remark-math": "^5.1.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^2.4.3"
"@docusaurus/module-type-aliases": "^3.0.0",
"yaml-loader": "^0.8.0"
},
"browserslist": {
"production": [

39
website/src/components/assets-context.jsx Normal file
View File

@ -0,0 +1,39 @@
import React, { createContext, useState, useContext, useEffect } from 'react';
const AssetsContext = createContext([]);
export const useAssets = () => useContext(AssetsContext);
export const AssetsProvider = ({ children }) => {
const [assets, setAssets] = useState([]);
useEffect(() => {
const fetchReleaseAssets = async () => {
try {
const response = await fetch('https://api.github.com/repos/openziti/zrok/releases/latest');
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
const filteredAssets = data.assets.map(asset => ({
name: asset.name,
url: asset.browser_download_url,
arch: asset.name.replace('\.tar\.gz','').split('_')[3]
}));
console.log("Fetched assets:", filteredAssets); // Log fetched assets
setAssets(filteredAssets);
} catch (error) {
console.error('Error fetching the release assets:', error);
// Handle the error state appropriately
}
};
fetchReleaseAssets();
}, []); // Empty dependency array ensures this runs once after component mounts
return (
<AssetsContext.Provider value={assets}>
{children}
</AssetsContext.Provider>
);
};

31
website/src/components/cat-yaml.jsx Normal file
View File

@ -0,0 +1,31 @@
import React from 'react';
import yaml from 'js-yaml';
import CodeBlock from '@theme/CodeBlock';
const ConcatenateYamlSnippets = ({ title, children }) => {
// Convert each YAML object to a string and concatenate
const concatenatedYaml = children.map(child => {
// Check if the child is a string or an object
if (typeof child === 'string') {
// If it's a string, use it as is
return child.trim();
} else {
// If it's an object, convert it to a YAML string
return yaml.dump(child).trim();
}
}).join('\n\n');
return (
<div>
<CodeBlock
language="yaml"
title={title}
>
{concatenatedYaml}
</CodeBlock>
</div>
);
};
export default ConcatenateYamlSnippets;

70
website/src/components/download-card.jsx Normal file
View File

@ -0,0 +1,70 @@
// download-card.jsx
import React from 'react';
import { useAssets } from '@site/src/components/assets-context';
import styles from '@site/src/css/download-card.module.css';
import { useColorMode } from '@docusaurus/theme-common';
const getFilenamePattern = (osName) => {
switch (osName) {
case 'Windows':
return 'windows';
case 'macOS':
return 'darwin';
case 'Linux':
return 'linux';
default:
return '';
}
};
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();
console.log("Assets in DownloadCard:", assets);
const filenamePattern = getFilenamePattern(osName);
const filteredLinks = assets.filter(asset => asset.name.includes(filenamePattern));
console.log("Filtered assets for", osName, "in DownloadCard:", filteredLinks);
return (
// <div className={colorMode === 'dark' ? styles.downloadCardDark : styles.downloadCardLight}>
<div className={styles.downloadCard}>
<div className={styles.imgContainer}>
<img src={osLogo} alt={`${osName} logo`} />
</div>
<h3>{osName}</h3>
{filteredLinks.length > 0 && (
<ul>
{filteredLinks.map((link, index) => (
<li key={index} className={styles.downloadButtons}>
<a href={link.url} className={styles.downloadLinks}>
{getArchitecturePattern(link.arch)}
</a>
</li>
))}
</ul>
)}
{guideLink && (
<div className={styles.cardFooter}>
<p>{infoText}</p>
<a href={guideLink}>GUIDE</a>
<p></p>
</div>
)}
</div>
);
};
export default DownloadCard;

104
website/src/css/download-card.module.css Normal file
View File

@ -0,0 +1,104 @@
:root {
--contrasting-background: #c4b7f5;
--container-border: 1px solid #adadad; /* Light gray border */
--button-background-hover: #9c84f9;
}
[data-theme="dark"] {
--contrasting-background: #4b359f;
--container-border: 1px solid #6d6d6d; /* Light gray border */
--button-background-hover: #251463;
}
.downloadContainer {
width: 100%; /* Adjust this value to fit your design */
display: flex;
flex-direction: row;
justify-content: center;
align-items: stretch;
gap: 9px; /* Adjust the space between cards */
padding: 20px; /* Space inside the container */
}
.downloadCard {
width: 30%; /* Adjust the width as needed */
box-sizing: border-box; /* Include padding and border in the width */
background-color: var(--sidebar-selected);
border-radius: 18px;
text-align: center;
display: flex;
flex-grow: 1; /* Allows the content area to grow and take up available space */
flex-direction: column; /* Stack footer vertically */
}
.downloadCard img {
width: auto; /* This will make the image take the full width of the card */
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;;
}
.cardFooter {
background-color: var(--contrasting-background);
border-top: var(--container-border);
padding: 10px;
margin-top: auto; /* Push the footer to the bottom */
border-bottom-left-radius: 18px;
border-bottom-right-radius: 18px;
}
.downloadCard ul {
list-style: none; /* Remove the default list style */
padding: 0; /* Remove the default padding */
margin: 0; /* Remove the default margin */
margin-bottom: 20px; /* Add some space between the list and the footer */
}
.downloadButtons {
display: inline-block; /* Allows width and height to be set */
margin: 5px; /* Spacing between buttons */
padding: 10px 15px; /* Size of the button */
text-align: center; /* Centers text within the button */
background-color: var(--contrasting-background); /* Background color - Bootstrap primary button color */
border: 1px var(--container-border); /* Border color - same as background for a solid button */
border-radius: 18px; /* Rounded corners */
transition: background-color 0.3s ease; /* Smooth transition for hover effect */
}
.downloadButtons:hover, .downloadButtons:focus {
background-color: var(--button-background-hover);
outline: none; /* Removes the outline on focus for a clean look */
}
.downloadLinks, .downloadLinks:hover, .downloadLinks:focus {
text-decoration: none; /* Removes the underline from links */
}
.downloadCard h3 {
margin-top: 10px;
}
.downloadCard .imgContainer {
background-color: var(--contrasting-background);
display: inline-block; /* Or 'block' depending on layout */
padding: 10px; /* Adjust padding as needed */
border-top-left-radius: 18px; /* Optional: for rounded corners */
border-top-right-radius: 18px; /* Optional: for rounded corners */
border-bottom: var(--container-border);
padding: 10px;
margin-bottom: auto; /* Push the footer to the bottom */
}
/* Responsive design for smaller screens */
@media (max-width: 768px) {
.downloadContainer {
flex-direction: column;
}
.downloadCard {
width: auto; /* Take full width on small screens */
max-width: none; /* Allow the card to take full width */
}
}

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 = ['Mac OS', 'Windows', 'Linux']
if (tabs.includes(osName)) {
setDefaultValue(osName);
} else {
setDefaultValue('Linux');
}
}, []); // 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;

47
website/static/img/logo-apple.svg Normal file
View File

@ -0,0 +1,47 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
<svg fill="#000000" height="800px" width="800px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 22.773 22.773" xml:space="preserve">
<g>
<g>
<path d="M15.769,0c0.053,0,0.106,0,0.162,0c0.13,1.606-0.483,2.806-1.228,3.675c-0.731,0.863-1.732,1.7-3.351,1.573
c-0.108-1.583,0.506-2.694,1.25-3.561C13.292,0.879,14.557,0.16,15.769,0z"/>
<path d="M20.67,16.716c0,0.016,0,0.03,0,0.045c-0.455,1.378-1.104,2.559-1.896,3.655c-0.723,0.995-1.609,2.334-3.191,2.334
c-1.367,0-2.275-0.879-3.676-0.903c-1.482-0.024-2.297,0.735-3.652,0.926c-0.155,0-0.31,0-0.462,0
c-0.995-0.144-1.798-0.932-2.383-1.642c-1.725-2.098-3.058-4.808-3.306-8.276c0-0.34,0-0.679,0-1.019
c0.105-2.482,1.311-4.5,2.914-5.478c0.846-0.52,2.009-0.963,3.304-0.765c0.555,0.086,1.122,0.276,1.619,0.464
c0.471,0.181,1.06,0.502,1.618,0.485c0.378-0.011,0.754-0.208,1.135-0.347c1.116-0.403,2.21-0.865,3.652-0.648
c1.733,0.262,2.963,1.032,3.723,2.22c-1.466,0.933-2.625,2.339-2.427,4.74C17.818,14.688,19.086,15.964,20.67,16.716z"/>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

97
website/static/img/logo-linux.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

2
website/static/img/logo-windows.svg Normal file
View File

@ -0,0 +1,2 @@
<?xml version="1.0" encoding="utf-8"?><!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
<svg fill="#000000" width="800px" height="800px" viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg"><title>ionicons-v5_logos</title><path d="M480,265H232V444l248,36V265Z"/><path d="M216,265H32V415l184,26.7V265Z"/><path d="M480,32,232,67.4V249H480V32Z"/><path d="M216,69.7,32,96V249H216V69.7Z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 425 B

7933
website/yarn.lock
View File

File diff suppressed because it is too large Load Diff