Merge pull request #480 from openziti/frontdoor_vanity_names

expect the unique-name option in reserved share wrappers

docker/compose/.gitignore

@@ -1,2 +1,2 @@
 .env
-compose.override.yml
+*compose.override.yml

docker/compose/zrok-public-reserved/compose.yml

@@ -38,6 +38,7 @@ services:
       STATE_DIRECTORY: /mnt  # zrok homedir in container
 
       # most relevant options
+      ZROK_UNIQUE_NAME:     # name is used to construct frontend domain name, e.g. "myapp" in "myapp.share.zrok.io"
       ZROK_BACKEND_MODE:    # web, caddy, drive, proxy
       ZROK_TARGET:          # backend target, is a path in container filesystem unless proxy mode
       ZROK_INSECURE:        # "--insecure" if proxy target has unverifiable TLS server certificate

docs/guides/_frontdoor-docker.mdx

@@ -19,25 +19,32 @@ When the project runs it will:
 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"
-  ```
+    ```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
-  ```
+    ```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
-  ```
+    ```bash
+    docker compose logs zrok-share
+    ```
 
-  ```buttonless title="Output"
-  zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/
-  ```
+    ```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.
 
@@ -78,50 +85,50 @@ With Caddy, you can balance the workload for websites or web services or share s
 
 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
+    ```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
-  ```
+    ```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
-  ```
+    ```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
-  ```
+    ```bash
+    docker compose up --detach
+    ```
 
 1. Note the new reserved share URL from the log.
 
-  ```bash
-  docker compose logs zrok-share
-  ```
+    ```bash
+    docker compose logs zrok-share
+    ```
 
-  ```buttonless title="Output"
-  INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
-  ```
+    ```buttonless title="Output"
+    INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
+    ```

docs/guides/_frontdoor-linux.mdx

@@ -89,6 +89,14 @@ Save the enable token from the zrok console in the configuration file.
 ZROK_ENABLE_TOKEN="14cbfca9772f"
 ```
 
+## Name your 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="/opt/openziti/etc/zrok/zrok-share.env"
+ZROK_UNIQUE_NAME="my-prod-app"
+```
+
 ## Use Cases
 
 You may change the target for the current backend mode, e.g. `proxy`, by editing the configuration file and restarting the service. The reserved subdomain will remain the same.

docs/guides/frontdoor.mdx

@@ -16,7 +16,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 <iframe width="100%" height="315" src="https://www.youtube.com/embed/5Vi8GKuTi_I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
-  ## Overview
+## Overview
 
 zrok frontends are the parts of zrok that proxy incoming public web traffic to zrok backend shares via OpenZiti. When you use zrok with a `zrok.io` frontend, you're using **zrok frontdoor**. `zrok.io` is zrok-as-a-service by NetFoundry, the team behind OpenZiti. You need a free account to use **zrok frontdoor**.
 

nfpm/zrok-share.bash

@@ -110,6 +110,10 @@ case "${ZROK_BACKEND_MODE}" in
     ;;
 esac
 
+[[ -n "${ZROK_UNIQUE_NAME:-}" ]] && {
+  ZROK_CMD+=" --unique-name ${ZROK_UNIQUE_NAME}"
+}
+
 ZROK_CMD+=" --backend-mode ${ZROK_BACKEND_MODE} ${ZROK_TARGET}"
 
 if [[ -n "${ZROK_SHARE_OPTS:-}" ]]; then

nfpm/zrok-share.env

@@ -56,28 +56,33 @@ ZROK_BACKEND_MODE="proxy"
 #ZROK_VERBOSE="--verbose"
 
 # you MAY set additional command-line options for the share; see "zrok reserve public --help" for hints
-# WARNING: changing this value requires provisioning a new frontend URL
+# WARNING: changes take effect the next time the frontend URL is reserved
 # NOTE: basic auth and oauth are mutually exclusive
 ZROK_SHARE_OPTS=""
 
 #
 ## ZROK FRONTEND 
 #
 
+# you MAY customize the share token that is used to construct the reserved subdomain; if not set a random
+# subdomain is reserved
+# WARNING: changes take effect the next time the frontend URL is reserved
+#ZROK_UNIQUE_NAME=""
+
 # you MAY set one OAuth2/OIDC provider; "google" and "github" are valid for the default instance api.zrok.io
-# WARNING: changing this value requires provisioning a new frontend URL
+# WARNING: changes take effect the next time the frontend URL is reserved
 # NOTE: basic auth and oauth are mutually exclusive
 #ZROK_OAUTH_PROVIDER="google"
 
 # you MAY restrict access to one or more email addresses or domains; must be a space-separate list
-# WARNING: changing this value requires provisioning a new frontend URL
+# WARNING: changes take effect the next time the frontend URL is reserved
 #ZROK_OAUTH_EMAILS="bob@acme.example.com alice@forge.example.com @corp.example.com"
 
 # you MAY require a password with HTTP basic authentication
-# WARNING: changing this value requires provisioning a new frontend URL
+# WARNING: changes take effect the next time the frontend URL is reserved
 # NOTE: basic auth and oauth are mutually exclusive
 #ZROK_BASIC_AUTH=""
 
 # set if self-hosting zrok and not using only the default frontend name 'public'; must be a space-separated list
-# WARNING: changing this value requires provisioning a new frontend URL
+# WARNING: changes take effect the next time the frontend URL is reserved
 #ZROK_FRONTENDS="public"

sdk/python/sdk/zrok/zrok/listener.py

@@ -1,6 +1,7 @@
-from zrok.environment.root import Root
 import openziti
-
+from zrok.environment.root import Root
+
+
 class Listener():
     shrToken: str
     root: Root
@@ -23,4 +24,4 @@ def listen(self):
         self.__server.listen()
 
     def close(self):
-        self.__server.close()
+        self.__server.close()