extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2025-01-11 16:38:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #464 from openziti/consolidate-share-scripts

Browse Source 
DRY by using the enable and share scripts
This commit is contained in:
Kenneth Bingham 2023-11-27 22:23:09 -05:00 committed by GitHub
commit 18bac012dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 254 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,28 +7,20 @@ 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}
@ -39,7 +31,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"

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

@ -7,42 +7,41 @@ 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/}
entrypoint:
- bash
- -euxc
- |
echo "DEBUG: HOME=$${HOME}"
ls -lA /mnt/.zrok/
exec zrok $${@}
command: -- share private --headless --backend-mode proxy ${ZROK_TARGET:-http://zrok-test:9090/}
depends_on:
zrok-enable:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"
# demo servers you can share with zrok
# demo server you can share with zrok
zrok-test:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
command: test endpoint --address 0.0.0.0 # 9090

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

@ -1,46 +1,7 @@
services:
# create Caddyfile
zrok-caddyfile:
image: busybox
# create Caddyfile
entrypoint:
- sh
- -euc
- |
ZROK_UPSTREAM_URL="${ZROK_TARGET:-http://zrok-test:9090}"
ZROK_UPSTREAM_HOST="$(echo $${ZROK_UPSTREAM_URL}|sed -E 's#^https?://([^/:]+).*#\1#')"
mkdir -p /mnt/.zrok
cat <<CADDYFILE >| /mnt/.zrok/Caddyfile
{
# GET /config/ and POST /load on this API to reload Caddy config
admin 0.0.0.0:2019
}
http:// {
bind {{ .ZrokBindAddress }}
handle_path /zrok-test/* {
reverse_proxy http://zrok-test:9090 {
header_up Host zrok-test
}
}
handle_path /zrok-static/* {
root * /mnt/.zrok/html
file_server browse
}
reverse_proxy /* $${ZROK_UPSTREAM_URL} {
header_up Host $${ZROK_UPSTREAM_HOST}
}
}
CADDYFILE
user: root
volumes:
- zrok_env:/mnt
# set file ownership
zrok-init:
image: busybox
depends_on:
zrok-caddyfile:
condition: service_completed_successfully
# matches uid:gid of "nobody" in zrok container image
command: chown -Rc 65534:65534 /mnt/
user: root
@ -53,117 +14,41 @@ 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
entrypoint: bash -x 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}
restart: unless-stopped
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:

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

@ -15,52 +15,46 @@ 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}
entrypoint: zrok-share.bash
depends_on:
zrok-enable:
condition: service_completed_successfully
volumes:
- zrok_env:/mnt/.zrok
- zrok_env:/mnt
ports: []
# - 127.0.0.1:2019:2019 # Caddy admin API
environment:
HOME: /mnt
PFXLOG_NO_JSON: "true"
# internal configuration
STATE_DIRECTORY: /mnt # zrok homedir in container
ZROK_FRONTEND_MODE: temp-public # tells zrok-share.bash to create a temporary subdomain and share until exit
# demo servers you can share with zrok
# most relevant options
ZROK_BACKEND_MODE: proxy # web, caddy, drive, proxy
ZROK_TARGET: http://zrok-test:9090 # backend target, is a path in container filesystem unless proxy mode
ZROK_INSECURE: # "--insecure" if proxy target has unverifiable TLS server certificate
ZROK_OAUTH_PROVIDER: # google, github
ZROK_OATH_EMAILS: # space-separated list of OAuth email addresses or @domain.tld to allow
ZROK_BASIC_AUTH: # username:password, mutually-exclusive with ZROK_OAUTH_PROVIDER
# least relevant options
ZROK_VERBOSE: # "--verbose"
ZROK_SHARE_OPTS: # additional arguments to "zrok share public" command
ZROK_FRONTENDS: # "public"
PFXLOG_NO_JSON: "true" # suppress JSON logging format
# demo server you can share with zrok
zrok-test:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
command: test endpoint --address 0.0.0.0 # 9090

12
docker/images/zrok/Dockerfile
View File

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

35
docs/guides/docker-share/_reserved_public_share.mdx → docs/guides/_frontdoor-docker.mdx
View File

@ -1,6 +1,6 @@
## Goal
Proxy a reserved public subdomain to a backend target with Docker.
Proxy a reserved public subdomain to a backend target with an always-on Docker Compose service.
## How it Works
@ -11,7 +11,7 @@ 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 `.env` configuration file
1. start sharing the target specified in the `ZROK_TARGET` environment variable
## Create the Docker Project
@ -23,7 +23,7 @@ When the project runs it will:
ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
```
1. Run the Compose project to start sharing the built-in demo web server.
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
@ -68,18 +68,13 @@ ZROK_OAUTH_PROVIDER="github"
ZROK_SHARE_OPTS="--oauth-email-domains @example.com"
```
### Password
## Caddy is Powerful
You can require a password by setting `ZROK_SHARE_OPTS` to specify additional command-line options to `zrok reserve
public`.
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)).
```bash title=".env"
ZROK_SHARE_OPTS="--basic-auth 'admin:passwd'"
```
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.
## Share Something Different
The reserved public share project uses zrok's `caddy` mode. Caddy accepts configuration as a Caddyfile that is mounted into the container ([zrok Caddyfile examples](https://github.com/openziti/zrok/tree/main/etc/caddy)).
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.
@ -94,7 +89,7 @@ The reserved public share project uses zrok's `caddy` mode. Caddy accepts config
}
```
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.
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:
@ -107,13 +102,21 @@ The reserved public share project uses zrok's `caddy` mode. Caddy accepts config
- ./Caddyfile:/mnt/.zrok/Caddyfile
```
1. Re-run the project to load the new configuration.
1. Start a new Docker Compose project or delete the existing state volume.
```bash
docker compose up --force-recreate --detach
docker compose down --volumes
```
1. Recall the reserved share URL from the log.
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

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

@ -1,7 +1,7 @@
## Goal
Proxy a reserved public subdomain to a backend target with a Linux system service.
Proxy a reserved public subdomain to a backend target with an always-on Linux system service.
## How it Works
@ -15,7 +15,7 @@ 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

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

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

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

@ -1,11 +1,12 @@
---
title: Docker Public Share
sidebar_position: 10
sidebar_label: Public Share
---
# Docker Public Share
With zrok and Docker, you can publicly share a web server that's running in a local container or anywhere that's reachable by the zrok container. The share can be reached through a temporary public URL that expires when the container is stopped. If you're looking for a reserved subdomain for the share, check out [zrok frontdoor](/guides/frontdoor.mdx).
With zrok and Docker, you can publicly share a web server that's running in a local container or anywhere that's reachable by the zrok container. The share can be reached through a public URL thats temporary or reserved (reusable).
Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.md).
## Walkthrough Video
@ -15,13 +16,13 @@ With zrok and Docker, you can publicly share a web server that's running in a lo
To follow this guide you will need [Docker](https://docs.docker.com/get-docker/) and [the Docker Compose plugin](https://docs.docker.com/compose/install/) for running `docker compose` commands in your terminal.
## Temporary or Reserved Public Share
## Begin Sharing with Docker Compose
A temporary public share is a great way to share a web server running in a container with someone else for a short time. A reserved public share is a great way to share a reliable web server running in a container with someone else for a long time.
A temporary public share is a great way to share a web server running in a container with someone else for a short time.
1. Make a folder on your computer to use as a Docker Compose project for your zrok public share.
1. In your terminal, change directory to the newly-created project folder.
1. Download either [the temporary public share project file](pathname:///zrok-public-share/compose.yml) or [the reserved public share project file](pathname:///zrok-public-reserved/compose.yml) into the project folder.
1. Download [the temporary public share project file](pathname:///zrok-public-share/compose.yml).
1. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named `.env` in the same folder like this:
```bash title=".env"
@ -54,7 +55,7 @@ This concludes sharing the demo web server. Read on to learn how to pivot to sha
## Proxy Any Web Server
The simplest way to share your web server is to set `ZROK_TARGET` (e.g. `https://example.com`) in the environment of the `docker compose up` command. When you restart the share will auto-configure for that upstream server URL. This applies to both temporary and reserved public shares.
The simplest way to share your web server is to set `ZROK_TARGET` (e.g. `https://example.com`) in the environment file.
```bash title=".env"
ZROK_TARGET="http://example.com:8080"
@ -62,7 +63,7 @@ ZROK_TARGET="http://example.com:8080"
## Require Authentication
You can require authentication for your public share by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` if you're using our hosted zrok.io, and any OIDC provider you've configured if self-hosting. You can parse the authenticated email address from the request cookie. Read more about the OAuth features in [this blog post](https://blog.openziti.io/the-zrok-oauth-public-frontend). This applies to both temporary and reserved public shares.
You can require authentication for your public share by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` with zrok.io. You could parse the authenticated email address from the request cookie if you're building a custom server app. Read more about the OAuth features in [this blog post](https://blog.openziti.io/the-zrok-oauth-public-frontend).
```bash title=".env"
ZROK_OAUTH_PROVIDER="github"
@ -70,6 +71,12 @@ ZROK_OAUTH_PROVIDER="github"
## Customize Temporary Public Share
This technique is useful for adding a containerized service to the project, or mounting a filesystem directory into the container to share as a static website or file server.
Any additional services specified in the override file will be merged with `compose.yml` when you `up` the project.
You may override individual values from in `compose.yml` by specifying them in the override file.
1. Create a file `compose.override.yml`. This example demonstrates sharing a static HTML directory `/tmp/html` from the Docker host's filesystem.
```yaml title="compose.override.yml"
@ -96,52 +103,6 @@ ZROK_OAUTH_PROVIDER="github"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```
## Customize Reserved Public Share
The reserved public share project uses zrok's `caddy` mode. Caddy accepts configuration as a Caddyfile that is mounted into the container ([zrok Caddyfile examples](https://github.com/openziti/zrok/tree/main/etc/caddy)).
1. Create a Caddyfile. This example demonstrates proxying two HTTP servers with a weighted round-robin load balancer.
```console title="Caddyfile"
http:// {
# zrok requires this bind address template
bind {{ .ZrokBindAddress }}
reverse_proxy /* {
to http://httpbin1:8080 http://httpbin2:8080
lb_policy weighted_round_robin 3 2
}
}
```
1. Create a file `compose.override.yml`. This example adds two `httpbin` containers for Caddy load balance, and masks the default Caddyfile with our custom one.
```yaml title="compose.override.yml"
services:
httpbin1:
image: mccutchen/go-httpbin # 8080/tcp
httpbin2:
image: mccutchen/go-httpbin # 8080/tcp
zrok-share:
volumes:
- ./Caddyfile:/mnt/.zrok/Caddyfile
```
1. Re-run the project to load the new configuration.
```bash
docker compose up --force-recreate --detach
```
1. Recall the reserved share URL from the log.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
```
## Destroy the zrok Environment
This destroys the Docker volumes containing the zrok environment secrets. The zrok environment can also be destroyed in the web console.

12
docs/guides/frontdoor.mdx
View File

@ -8,8 +8,8 @@ import OsTabs from '@theme/OsTabs';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
// import Details from '@theme/MDXComponents/Details';
import LinuxService from './_linux-service.mdx';
import ReservedDocker from './docker-share/_reserved_public_share.mdx';
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.
@ -34,7 +34,7 @@ If you'd prefer to run zrok in Docker, you can follow the same Docker instructio
<TabItem value="Mac OS">
On macOS, zrok frontdoor is implemented as a Docker share project which reserves a public subdomain for your website or service.
On macOS, zrok frontdoor is implemented as a Docker Compose project which reserves a public subdomain for your website or service.
<ReservedDocker/>
@ -42,10 +42,14 @@ On macOS, zrok frontdoor is implemented as a Docker share project which reserves
<TabItem value="Windows">
On Windows, zrok frontdoor is implemented as a Docker share project which reserves a public subdomain for your website or service.
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)

2
nfpm/README.md
View File

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

6
nfpm/zrok-enable.bash
View File

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

61
nfpm/zrok-share.bash
View File

@ -7,17 +7,29 @@ set -o errexit
set -o nounset
set -o pipefail
share_reserved(){
local token="$1"
local target="$2"
shift 2
local opts="${*:-}"
local zrok_cmd="share reserved ${token} --headless ${opts} --override-endpoint ${target}"
echo "INFO: running: zrok ${zrok_cmd}"
exec zrok ${zrok_cmd}
}
if ! command -v jq &>/dev/null; then
echo "ERROR: jq is needed but not installed" >&2
exit 1
fi
# set HOME to the first colon-sep dir in STATE_DIRECTORY inherited from systemd, e.g. /var/lib/zrok-share
# 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,28 +42,37 @@ 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
}
fi
[[ -n "${ZROK_BACKEND_MODE:-}" ]] || {
echo "WARNING: ZROK_BACKEND_MODE was not defined, assuming mode 'proxy'." >&2
ZROK_BACKEND_MODE="proxy"
}
case "${ZROK_BACKEND_MODE}" in
proxy)
if ! [[ "${ZROK_TARGET}" =~ ^https?:// ]]; then
@ -88,10 +109,13 @@ else
" 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
@ -102,10 +126,16 @@ else
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
echo "INFO: running: zrok ${ZROK_CMD}"
if [[ "${ZROK_FRONTEND_MODE:-}" == temp-public ]]; then
# share until exit
exec zrok ${ZROK_CMD}
else
# reserve and continue
zrok ${ZROK_CMD} | jq -rc | tee ~/.zrok/reserved.json
# share the reserved backend target until exit
if ! [[ -s ~/.zrok/reserved.json ]]; then
echo "ERROR: empty or missing $(realpath ~/.zrok)/reserved.json" >&2
exit 1
@ -122,11 +152,8 @@ else
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_RESERVED_TOKEN} ${ZROK_TARGET}"
ZROK_CMD+=" ${ZROK_VERBOSE:-} ${ZROK_INSECURE:-}"
if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then
ZROK_CMD+=" ${ZROK_SHARE_OPTS}"
share_reserved ${ZROK_CMD}
fi
echo "INFO: running: zrok ${ZROK_CMD}"
exec zrok ${ZROK_CMD}
fi