mirror of
https://github.com/openziti/zrok.git
synced 2024-11-22 16:13:47 +01:00
Merge branch 'main' of github.com:openziti/zrok into go-sdk-move
This commit is contained in:
Cam
commit
aa7a65231b
2
.github/workflows/deploy-doc-site.yml
vendored
2
.github/workflows/deploy-doc-site.yml
vendored
@ -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
|
||||
|
||||
@ -1,5 +1,13 @@
|
||||
# CHANGELOG
|
||||
|
||||
## 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`).
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
8
docs/concepts/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Concepts",
|
||||
"position": 30,
|
||||
"link": {
|
||||
"type": "doc",
|
||||
"id": "concepts/index"
|
||||
}
|
||||
}
|
||||
@ -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,6 +1,7 @@
|
||||
---
|
||||
sidebar_position: 200
|
||||
---
|
||||
|
||||
# Hosting
|
||||
|
||||
## Self-Hosted
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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 |
|
||||
@ -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 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:
|
||||
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
|
||||
|
||||
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"
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Guides",
|
||||
"position": 30,
|
||||
"position": 50,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
|
||||
127
docs/guides/_frontdoor-docker.mdx
Normal file
127
docs/guides/_frontdoor-docker.mdx
Normal 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/
|
||||
```
|
||||
@ -1,11 +1,9 @@
|
||||
---
|
||||
title: Linux Service
|
||||
sidebar_position: 40
|
||||
---
|
||||
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 a Linux service.
|
||||
Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
|
||||
|
||||
## How it Works
|
||||
|
||||
@ -19,28 +17,70 @@ 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 in the configuration file
|
||||
1. start sharing the target specified as `ZROK_TARGET` in the environment file
|
||||
|
||||
## Installation
|
||||
|
||||
1. Download the OpenZiti install script.
|
||||
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 -sSo ./openziti-install.bash https://get.openziti.io/install.bash
|
||||
curl -sSLf https://get.openziti.io/install.bash \
|
||||
| sudo bash -s zrok-share
|
||||
```
|
||||
|
||||
1. Inspect the script to ensure it is suitable to run as root on your system.
|
||||
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
|
||||
less ./openziti-install.bash
|
||||
```bash title="Ubuntu, Debian"
|
||||
sudo sudo apt install zrok-share
|
||||
```
|
||||
|
||||
1. Run the script as root to install the `zrok-share` package.
|
||||
|
||||
```bash
|
||||
sudo bash ./openziti-install.bash 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.
|
||||
@ -64,6 +104,12 @@ 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`.
|
||||
@ -73,15 +119,6 @@ ZROK_TARGET="/var/www/html"
|
||||
ZROK_BACKEND_MODE="web"
|
||||
```
|
||||
|
||||
### WebDAV Server
|
||||
|
||||
This uses zrok's `drive` backend mode to serve a directory of static files as a WebDAV resource. 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"
|
||||
```
|
||||
|
||||
### 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.
|
||||
@ -91,6 +128,17 @@ 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.
|
||||
@ -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.
|
||||
|
||||
@ -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
56
docs/guides/frontdoor.mdx
Normal 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
55
docs/guides/install/_ansible_repo_setup.yaml
Normal 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
8
docs/guides/install/_category_.json
Normal file
@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Install",
|
||||
"position": 10,
|
||||
"link": {
|
||||
"type": "doc",
|
||||
"id": "guides/install/index"
|
||||
}
|
||||
}
|
||||
31
docs/guides/install/index.mdx
Normal file
31
docs/guides/install/index.mdx
Normal 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
195
docs/guides/install/linux.mdx
Normal 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
55
docs/guides/install/macos.mdx
Normal 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
52
docs/guides/install/windows.mdx
Normal 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]
|
||||
```
|
||||
46
docs/guides/self-hosting/instance-configuration.mdx
Normal file
46
docs/guides/self-hosting/instance-configuration.mdx
Normal 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.
|
||||
|
||||
@ -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.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 72 KiB |
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
# 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,103 +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}"
|
||||
if [[ -n "${ZROK_OAUTH_EMAILS:-}" ]]; then
|
||||
for EMAIL in ${ZROK_OAUTH_EMAILS}; do
|
||||
ZROK_CMD+=" --oauth-email-domains ${EMAIL}"
|
||||
done
|
||||
fi
|
||||
elif [[ -n "${ZROK_BASIC_AUTH:-}" ]]; then
|
||||
ZROK_CMD+=" --basic-auth ${ZROK_BASIC_AUTH}"
|
||||
fi
|
||||
echo "INFO: running: zrok ${ZROK_CMD}"
|
||||
zrok ${ZROK_CMD} | jq -rc | tee ~/.zrok/reserved.json
|
||||
fi
|
||||
|
||||
if ! [[ -s ~/.zrok/reserved.json ]]; then
|
||||
echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&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}"
|
||||
if [[ -n "${ZROK_OAUTH_EMAILS:-}" ]]; then
|
||||
for EMAIL in ${ZROK_OAUTH_EMAILS}; do
|
||||
ZROK_CMD+=" --oauth-email-domains ${EMAIL}"
|
||||
done
|
||||
fi
|
||||
elif [[ -n "${ZROK_BASIC_AUTH:-}" ]]; then
|
||||
ZROK_CMD+=" --basic-auth ${ZROK_BASIC_AUTH}"
|
||||
fi
|
||||
|
||||
echo "INFO: running: zrok ${ZROK_CMD}"
|
||||
|
||||
if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
|
||||
# share until exit
|
||||
exec zrok ${ZROK_CMD}
|
||||
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
|
||||
# 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
|
||||
echo "INFO: zrok public URLs: ${ZROK_PUBLIC_URLS}"
|
||||
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
|
||||
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}"
|
||||
exec zrok ${ZROK_CMD}
|
||||
fi
|
||||
|
||||
1
website/.nvmrc
Normal file
1
website/.nvmrc
Normal file
@ -0,0 +1 @@
|
||||
v18.18.2
|
||||
@ -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
11781
website/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -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
39
website/src/components/assets-context.jsx
Normal 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
31
website/src/components/cat-yaml.jsx
Normal 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
70
website/src/components/download-card.jsx
Normal 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
104
website/src/css/download-card.module.css
Normal 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
29
website/src/theme/OsTabs/index.js
Normal 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
47
website/static/img/logo-apple.svg
Normal 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>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
97
website/static/img/logo-linux.svg
Normal file
97
website/static/img/logo-linux.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 14 KiB |
2
website/static/img/logo-windows.svg
Normal file
2
website/static/img/logo-windows.svg
Normal 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>
|
||||
|
After Width: | Height: | Size: 425 B |
7933
website/yarn.lock
7933
website/yarn.lock
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user