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

simplify docker share guides

Browse Source
This commit is contained in:
Kenneth Bingham 2024-04-23 14:33:41 -04:00
parent 550a45725b
commit f0fbab1fe6
No known key found for this signature in database
GPG Key ID: 31709281860130B6
14 changed files with 267 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGELOG.md
View File

@ -1,5 +1,11 @@
# CHANGELOG
## v0.4.28
CHANGE: the container images run as "ziggy" (UID 2171) instead of the generic restricted user "nobody" (UID 65534). This reduces the risk of unexpected file permissions when binding the Docker host's filesystem to a zrok container.
CHANGE: the Docker sharing guides were simplified and expanded
## v0.4.27
FEATURE: New `vpn` backend mode. Use `sudo zrok share private --backend-mode vpn` on the _VPN server_ host, then `sudo zrok access private <token>` on _VPN client_ machine. Works with reserved shares using `zrok reserve private --backend-mode vpn`. Use `<target>` parameter to override default VPN network settings `zrok share private -b vpn 192.168.255.42/24` -- server IP is `192.168.255.42` and VPN netmask will be `192.168.255.0/24`. Client IPs are assigned automatically from netmask range.

6
docker/images/zrok/Dockerfile
View File

@ -1,7 +1,7 @@
# this builds docker.io/openziti/zrok
ARG ZITI_CLI_TAG="0.32.1"
ARG ZITI_CLI_TAG="1.0.0"
ARG ZITI_CLI_IMAGE="docker.io/openziti/ziti-cli"
# this builds docker.io/openziti/ziti-controller
FROM ${ZITI_CLI_IMAGE}:${ZITI_CLI_TAG}
ARG ARTIFACTS_DIR=./dist
@ -40,5 +40,5 @@ RUN chmod 0755 \
/usr/local/bin/zrok-enable.bash \
/usr/local/bin/zrok-share.bash
USER nobody
USER ziggy
ENTRYPOINT [ "zrok" ]

2
docs/concepts/hosting.md
View File

@ -6,7 +6,7 @@ sidebar_position: 200
## Self-Hosted
`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/self_hosting_guide.md) instance of `zrok` as well. `zrok` is
`zrok` is not limited to a managed offering. You can [host your own](/guides/self-hosting/linux.mdx) instance of `zrok` as well. `zrok` is
also freely available as open source software hosted by GitHub under a very permissive Apache v2 license.
## Managed Service

2
docs/concepts/index.md
View File

@ -10,4 +10,4 @@ sidebar_position: 25
Sharing with `zrok` can be either [`public`](./sharing-public.md) or [`private`](./sharing-private.md).
Naturally, regular web-based resources can be shared but `zrok` also includes support for sharing raw [TCP](./tunnels.md) and [UDP](./tunnels.md) network connections, and also includes a [website and file sharing](./files.md) feature.
Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](../guides/self-hosting/self_hosting_guide.md).
Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](/guides/self-hosting/linux.mdx).

2
docs/getting-started.mdx
View File

@ -356,7 +356,7 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares
## Self-Hosting an Instance
Interested in self-hosting your own `zrok` 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/linux.mdx) for details.
[openziti]: https://docs.openziti.io/docs/learn/introduction/ "OpenZiti"
[ zrok-download]: https://zrok.io "zrok Download"

134
docs/guides/_frontdoor-docker.mdx
View File

@ -1,134 +0,0 @@
## 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. Name the Share
This unique name becomes part of the domain name of the share, e.g. `https://my-prod-app.in.zrok.io`. A random name is generated if you don't specify one.
```bash title=".env"
ZROK_UNIQUE_NAME="my-prod-app"
```
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_OAUTH_EMAILS="alice@example.com *@acme.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/
```

3
docs/guides/docker-share/_category_.json
View File

@ -2,6 +2,7 @@
"label": "Docker Share",
"position": 40,
"link": {
"type": "generated-index"
"type": "doc",
"id": "guides/docker-share/index"
}
}

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

@ -1,12 +1,16 @@
---
title: Docker Private Share
sidebar_position: 20
sidebar_label: Private Share
---
## Goal
# Docker Private Share
Privately share a Docker Compose service with a separate zrok environment and a permanent zrok share token.
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.
## Overview
With zrok, you can privately share a service that's running in Docker. You need a zrok private share running somewhere that it can reach the service you're sharing, and a zrok private access running somewhere else where you want to use the private share. Together, the private share and private access form a private point-to-point tunnel.
Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.md).
@ -14,6 +18,16 @@ Here's a short article with an overview of [private sharing with zrok](/concepts
<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>
## How it Works
The Docker Compose project uses your zrok account token to reserve a private share token 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 private share token for the service unless `/mnt/.zrok/reserved.json` exists
1. start sharing the target specified in the `ZROK_TARGET` environment variable
## Before You Begin
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.

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

@ -1,10 +1,16 @@
---
title: Docker Public Share
title: Docker Compose Public Share
sidebar_position: 10
sidebar_label: 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).
## Goal
Publicly share a Docker Compose service with a separate zrok environment and a permanent zrok share URL.
## Overview
With zrok, you can publicly share a service that's running in Docker. You need a zrok public share running somewhere that it can reach the service you're sharing. As long as that public share is running and your service is available, anyone with the address can use your service.
Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.md).
@ -12,101 +18,134 @@ Here's a short article with an overview of [public sharing with zrok](/concepts/
<iframe width="100%" height="315" src="https://www.youtube.com/embed/ycov--9ZtB4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
## Before You Begin
## How it Works
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.
The Docker Compose project uses your zrok account token to reserve a public subdomain and keep sharing the backend
target.
## Begin Sharing with Docker Compose
When the project runs it will:
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. 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
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 [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:
## Create the Docker Project
```bash title=".env"
ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
```
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:
1. Set the zrok API endpoint if self-hosting zrok. Skip this if using zrok.io.
```bash title=".env"
ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
```
```bash title=".env"
ZROK_API_ENDPOINT="https://zrok.example.com"
```
1. Name the Share
1. Run the Compose project to start sharing the built-in demo web server.
This unique name becomes part of the domain name of the share, e.g. `https://my-prod-app.in.zrok.io`. A random name is generated if you don't specify one.
```bash
docker compose up --detach
```
```bash title=".env"
ZROK_UNIQUE_NAME="my-prod-app"
```
1. Get the public share URL from the output of the `zrok-share` service or by peeking in the zrok console where the share will be graphed.
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 logs zrok-share
```
```bash
docker compose up --detach
```
```buttonless title="Output"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```
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.
This concludes sharing the demo web server. Read on to learn how to pivot to sharing any web server leveraging additional zrok backend modes.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```
This concludes the minimum steps to begin sharing the demo web server. Read on to learn how to pivot to sharing any website or web service by leveraging additional zrok backend modes.
## Proxy Any Web Server
The simplest way to share your web server is to set `ZROK_TARGET` (e.g. `https://example.com`) in the environment file.
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 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).
You can require a password or an OAuth login with certain email addresses.
### OAuth Email
You can allow specific email addresse patterns by setting `ZROK_OAUTH_PROVIDER` to `github` or `google` and
`ZROK_OAUTH_EMAILS`. 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_OAUTH_EMAILS="alice@example.com *@acme.example.com"
```
## Customize Temporary Public Share
## Caddy is Powerful
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.
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)).
Any additional services specified in the override file will be merged with `compose.yml` when you `up` the project.
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.
You may override individual values from in `compose.yml` by specifying them in the override file.
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 file `compose.override.yml`. This example demonstrates sharing a static HTML directory `/tmp/html` from the Docker host's filesystem.
1. Create a Caddyfile. This example demonstrates proxying two HTTP servers with a weighted round-robin load balancer.
```yaml title="compose.override.yml"
services:
zrok-share:
command: share public --headless --backend-mode web /tmp/html
volumes:
- /tmp/html:/tmp/html
```
1. Re-run the project to load the new configuration.
```bash
docker compose up --force-recreate --detach
```
1. Get the new tempoary public share URL for the `zrok-share` container.
```bash
docker compose logs zrok-share
```
```buttonless title="Output"
zrok-public-share-1 | https://w6r1vesearkj.in.zrok.io/
```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
}
}
```
## Destroy the zrok Environment
1. Create a file `compose.override.yml`. This example adds two `httpbin` containers for load balancing, and mounts the Caddyfile into the container.
This destroys the Docker volumes containing the zrok environment secrets. The zrok environment can also be destroyed in the web console.
```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
```
```bash
docker compose down --volumes
```
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/
```

112
docs/guides/docker-share/index.mdx Normal file
View File

@ -0,0 +1,112 @@
---
title: Getting Started with Docker
---
import Details from '@theme/MDXComponents/Details';
## Overview
To follow the guides in this section you will need [Docker](https://docs.docker.com/get-docker/).
You have the option to enable a `zrok` account on the Docker host and mount it on the container or you can use the provided Docker Compose project files (`compose.yml`) to enable a separate `zrok` environment for each project.
This page provides `docker` and `docker compose` examples of mounting the host's `zrok` environment on the container. You'll need to first [enable zrok on the Docker host](/docs/getting-started/#installing-the-zrok-command) to use this approach.
## Permanent Public Share
Let's say you have a `compose.yml` file that defines a web app known within the project's bridge network as `https://myapp:8080` and you want to publish it as a reliable, public site.
1. Reserve a subdomain by running `zrok reserve public --unique-name "myapp" https://myapp:8080` on the Docker host.
1. Merge this YAML with `compose.yml` or save it in the same directory as `compose.override.yml` to let `docker compose up` merge it for you.
```yaml
services:
zrok:
image: openziti/zrok
restart: unless-stopped
user: "${UID}"
volumes:
- ${HOME}/.zrok:/.zrok
environment:
PFXLOG_NO_JSON: "true"
command: share reserved "myapp" --headless
```
The reserved share will be available at `https://myapp.share.zrok.io` each time the `zrok` container starts up.
## Temporary Public Share
Let's say you have a web server running on the host's private network at `https://10.11.12.13:8080`. With one additional `docker` command, you can share the web server publicly as long as the `zrok` container stays running.
```bash title="BASH"
docker run \
--rm \
--network=host \
--volume ~/.zrok:/.zrok \
--user "${UID}" \
openziti/zrok share public \
--headless \
https://10.11.12.13:8080
```
<Details>
<summary>PowerShell</summary>
```powershell
docker.exe run `
--rm `
--network "host" `
--volume "${env:USERPROFILE}\.zrok:/.zrok" `
--user "1000" `
openziti/zrok share public `
--headless `
https://10.11.12.13:8080
```
</Details>
<Details>
<summary>Command Prompt (batch)</summary>
```cmd
docker.exe run ^
--rm ^
--network "host" ^
--volume "%USERPROFILE%\.zrok:/.zrok" ^
--user "1000" ^
openziti/zrok share public ^
--headless ^
https://10.11.12.13:8080
```
</Details>
<Details>
<summary>Windows Subsystem for Linux (WSL)</summary>
```bash
docker run \
--rm \
--network "host" \
--volume "/mnt/c/Users/$(powershell.exe -Command 'Write-Output $env:USERNAME' | tr -d '\r')/.zrok:/.zrok" \
--user "$UID" \
openziti/zrok share public \
--headless \
https://10.11.12.13:8080
```
</Details>
The public share URL appears near the beginning of the container's log.
Let's break down those options and arguments.
1. `--rm` don't save this container because it's providing a temporary public share that's destroyed when the container stops
1. `--network=host` shares the host's network with the container so that the container can reach the web server directly. This is always necessary when the web server is listening only on the host's loopback interface, e.g., `https://::1:8080`, and may not be strictly necessary if the target is routeable from the default Docker bridge.
1. `--volume ~/.zrok:/.zrok` mounts the `zrok` configuration from the Docker host into the container.
1. `--user "${UID}:${GID}"` sets the container's user to the current user on the Docker host to avoid permission issues with reading the mounted `zrok` configuration.
1. `openziti/zrok` is the `zrok` Docker image.
1. `share public` is the `zrok` command to share the target publicly until zrok exits.
1. `--headless` runs the `zrok` command without the interactive terminal UI.
1. `https://10.11.12.13:8080` is the target web server to share.

20
docs/guides/frontdoor.mdx
View File

@ -8,7 +8,6 @@ hide_table_of_contents: true
import OsTabs from '@theme/OsTabs';
import TabItem from '@theme/TabItem';
import LinuxService from './_frontdoor-linux.mdx';
import ReservedDocker from './_frontdoor-docker.mdx';
import ThemedImage from '@theme/ThemedImage';
import useBaseUrl from '@docusaurus/useBaseUrl';
@ -37,8 +36,7 @@ Choose between installing the Linux package or running zrok with Docker (Linux,
queryString="os"
values={[
{ label: 'Linux', value: 'Linux', },
{ label: 'macOS', value: 'Mac OS', },
{ label: 'Windows', value: 'Windows', },
{ label: 'Docker', value: 'Docker', },
]}
>
@ -46,25 +44,13 @@ Choose between installing the Linux package or running zrok with Docker (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">
<TabItem value="Docker">
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/>
On macOS and Windows, zrok frontdoor is implemented as a Docker Compose project which reserves a public subdomain for your website or service and manages a zrok environment that's separate from the Docker host. [Link to the Docker Public Share Guide](/guides/docker-share/docker_public_share_guide.md)
</TabItem>

13
docs/guides/self-hosting/self_hosting_guide.md → docs/guides/self-hosting/linux.mdx
View File

@ -1,10 +1,9 @@
---
sidebar_position: 40
sidebar_label: Linux VPS
title: Self-Hosting Guide for Linux
sidebar_label: Linux
---
# Self-Hosting Guide for Linux
## Walkthrough Video
<iframe width="100%" height="315" src="https://www.youtube.com/embed/870A5dke_u4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
@ -146,6 +145,8 @@ Notice this warning:
[ 0.120] WARNING zrok/controller.Bootstrap: missing public frontend for ziti id 'sqJRAINSiB'; please use 'zrok admin create frontend sqJRAINSiB public https://{token}.your.dns.name' to create a frontend instance
```
If you find it necessary to re-run the `zrok admin bootstrap` command, you may need to add the `--skip-frontend` flag to avoid re-creating the default `public` frontend's Ziti identity and router policy.
## Run zrok Controller
The `zrok` bootstrap process wants us to create a "public frontend" for our service. `zrok` uses public frontends to allow users to specify where they would like public traffic to ingress from.
@ -188,7 +189,7 @@ zitiLogin
ziti edge list identities
```
The id is shown for the "frontend" identity.
The id is shown for the frontend identity named "public."
Nice work! The `zrok` controller is fully configured now that you have created the zrok frontend.
@ -217,10 +218,10 @@ $ zrok access public etc/http-frontend.yml
[ 0.002] INFO main.(*accessPublicCommand).run: {
...
}
[ 0.002] INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded 'frontend' identity
[ 0.002] INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded 'public' identity
```
This process uses the `frontend` identity created during the bootstrap process to provide public access for the `zrok` deployment. It is expected that the configured listener for this `frontend` corresponds to the DNS template specified when creating the public frontend record above.
The zrok frontend uses the `public` identity created during the bootstrap process to securely access zrok backends. to provide public access for the `zrok` deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.
## Invite Yourself

18
docs/guides/self-hosting/nginx_tls_guide.md
View File

@ -1,9 +1,9 @@
---
sidebar_position: 50
sidebar_label: Nginx TLS
sidebar_label: NGINX TLS
---
# Nginx Reverse Proxy for zrok
# NGINX Reverse Proxy for zrok
## Walkthrough Video
@ -11,7 +11,7 @@ sidebar_label: Nginx TLS
## Before You Begin
I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to [Self-Hosting Guide](./self_hosting_guide.md) if you still need to spin those up.
I'll assume you have a running zrok controller and frontend and wish to front both with NGINX providing server TLS. Go back to [Self-Hosting Guide](./linux.mdx) if you still need to spin those up.
## Choose a Reverse Proxy Address
@ -29,9 +29,9 @@ You must complete a DNS challenge to obtain a wildcard certificate from Let's En
sudo certbot certonly --manual
````
## [Install Nginx](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)
## [Install NGINX](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)
## Configure Nginx
## Configure NGINX
```
server {
@ -78,15 +78,15 @@ server {
}
```
## Restart Nginx
## Restart NGINX
Load the new configuration by restarting Nginx. Check the logs to make sure it's happy.
Load the new configuration by restarting NGINX. Check the logs to make sure it's happy.
> Started A high performance web server and a reverse proxy server.
## Check the Firewall
If you followed the non-TLS quickstart then you may have opened 8080,108080/tcp in your firewall. You can go ahead and replace those exceptions with 443/tcp because only Nginx needs to be reachable for zrok to function.
If you followed the non-TLS quickstart then you may have opened 8080,108080/tcp in your firewall. You can go ahead and replace those exceptions with 443/tcp because only NGINX needs to be reachable for zrok to function.
## Update the zrok Frontend
@ -99,7 +99,7 @@ $ zrok admin list frontends
2NiDTRYUww18 7DsLh9DXG public http://{token}.zrok.quigley.com:8080 2023-01-19 05:29:20.793 +0000 UTC 2023-01-19 06:17:25 +0000 UTC
```
Update the URL template to use Nginx.
Update the URL template to use NGINX.
```bash
$ zrok admin update frontend 2NiDTRYUww18 --url-template https://{token}.zrok.quigley.com:443

4
website/docusaurus.config.js
View File

@ -34,6 +34,10 @@ const config = {
'@docusaurus/plugin-client-redirects',
{
redirects: [
{
to: '/docs/guides/self-hosting/linux',
from: ['/docs/guides/self-hosting/self_hosting_guide'],
},
{
to: '/docs/guides/self-hosting/metrics-and-limits/configuring-limits',
from: ['/docs/guides/metrics-and-limits/configuring-limits'],