extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2025-01-03 04:29:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

split docker shares between frontdoor (reserved) and temp

Browse Source
This commit is contained in:
Kenneth Bingham 2023-11-27 22:20:04 -05:00
parent 980a03c760
commit de68bcfc50
No known key found for this signature in database
GPG Key ID: 31709281860130B6
5 changed files with 47 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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.

10
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.
@ -48,4 +48,8 @@ On Windows, zrok frontdoor is implemented as a Docker Compose project which rese
</TabItem>
</OsTabs>
</OsTabs>
## Concepts
Overview of [zrok reserved shares](/concepts/sharing-reserved.md)