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

@@ -22,6 +22,13 @@ When the project runs it will:
     ```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.
 

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.

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,7 +56,7 @@ 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=""
 
@@ -64,20 +64,25 @@ 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,5 +1,6 @@
-from zrok.environment.root import Root
 import openziti
+from zrok.environment.root import Root
+
 
 class Listener():
     shrToken: str