Probably a simple answer but couldn't quite find the answer in the docs. I have a self hosted zrok server that is properly configured to use SSL via Caddy. Everything seems to work except that in zrok the fronend endpoints show up as http://{url}:8080
I would like them to just show https://{url}
the SSL urls work fine and am able to browse to the public endpoints but I have to change it in the browser. Is there a config option to do this?
Are you following the Linux or Docker guide for self-hosted zrok instance?
I am using the Docker guide but just realized when i deleted the shares and redeployed they came up as https://{url}:443 so all is good. Thanks for the quite response.
Cool. Yes, for the Docker guide the included, optional compose file that provides Caddy will do the following step automatically.
For others' benefit, if you encounter this issue with a self-hosted zrok instance running on Linux, you must update the frontend URL template to send public share visitors to Caddy.
zrok admin update frontend "someFrontendUniqueID" --url-template 'https://{token}.my.caddy.domain:443'
Be sure to preserve the https://{token}. part of the example above verbatim. Replace the "my.caddy.domain:443" with Caddy's FQDN:PORT.
I guess I have one other question, when docker instances quit their shares seem to just hang out there. Is there any cleanup mechanism for this?
If the shares are reserved that would be the expected behavior. I'm not familiar enough with the way this is working in docker at the moment to know if that's expected or not.
If the shares are not reserved then this isn't what I would expect. I'll try to figure it out at some point this week.
If temporary shares are left behind it's possible the container didn't terminate gracefully. zrok will normally delete the temporary share during shutdown. You can clean them up in the web console if this happens.
Example of a non-graceful exit: docker kill zrok-share.
The template I am using the create the containers is this:
services:
# set file ownership
zrok-init:
image: busybox
# matches uid:gid of "ziggy" in zrok container image
command: chown -Rc 2171:2171 /mnt/
user: root
volumes:
- zrok_env:/mnt
# enable zrok environment
zrok-enable:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
depends_on:
zrok-init:
condition: service_completed_successfully
entrypoint: zrok-enable.bash
volumes:
- zrok_env:/mnt
environment:
HOME: /mnt
ZROK_ENABLE_TOKEN: "${TOKEN}"
ZROK_API_ENDPOINT: "${ENDPOINT}"
ZROK_ENVIRONMENT_NAME: "${ENV_NAME}"
# reserve zrok frontend subdomain and start sharing the target
zrok-share:
image: ${ZROK_CONTAINER_IMAGE:-docker.io/openziti/zrok}
restart: unless-stopped
depends_on:
zrok-enable:
condition: service_completed_successfully
entrypoint: zrok-share.bash
volumes:
- zrok_env:/mnt
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
# internal configuration
HOME: /mnt # zrok homedir in container
# most relevant options
ZROK_UNIQUE_NAME: "${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: "http://host.docker.internal:${TARGET_PORT}" # 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_OAUTH_EMAILS: # allow space-separated list of OAuth email address glob patterns
ZROK_BASIC_AUTH: # username:password, mutually-exclusive with ZROK_OAUTH_PROVIDER
# 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
volumes:
zrok_env:
When the container stops the shares don't get removed. Is there an API that could be called instead of using the webapp?
Now it makes sense. The Docker public share example that I think you customized provides a reserved (permanent) share. It will keep sharing the same target on the same public URL each time you run the container.
You want a temporary public share instead.
Here's a one liner for a temporary share: Getting Started with Docker | Zrok
If you'd prefer to create a temporary share in your compose file you can set this env var to override the default "reserved-public."
ZROK_FRONTEND_MODE="temp-public"
Here's an inventory of all the variables you can set: zrok/nfpm/zrok-share.env at main · openziti/zrok · GitHub
Ok so is it not required to run the zrok-init and zrok-enable services to start the share?
Those are useful if your goal is a reliable, reserved share that's always on in the background. They provide a separate zrok environment for your permanent share.
Only the zrok binary is necessary. The rest, e.g., Docker or Linux services, may help you do what you want to do.
Ok, when I use the ZROK_FRONTEND_MODE="temp-public" and I stop the container it does remove the share, but it uses a random UNIQUE_NAME even though I specified one in the config? Also the share is removed but the environment is not. Is there a way to clean up environments as well?
That's what I'd expect because temporary shares always use a random token. The reserved token, too, is random by default but can be set to a "vanity" string with the unique name feature.
The Docker examples don't automatically clean up the zrok environment. Here's two ways to do that.
-
Run
zrok disablein the running container before destroying the compose project's containers and storage.docker compose exec zrok-share zrok disable docker compose down --volumes -
In the web console, choose "Delete your environment" from the "Actions" tab for any environment. This will recursively delete that environment's shares and accesses.
Is there any exposed API to do this?
Here's the latest API spec: https://raw.githubusercontent.com/openziti/zrok/v0.4.39/specs/zrok.yml
I'll work on adding an example using cURL.
Also, based on what you said should the UNIQUE_NAME vanity string will not work with temporary shares?
Correct about UNIQUE_NAME. That's a feature of reserved shares.
For what it's worth, there is no difference between a reserved share and an ephemeral share, other than that the reserved share is retained across zrok share invocations. Technically they're identical, with the same features and capabilities.
well and the ability to give a ephemeral share a vanity name
If you're going to use the same name over and over (i.e. in a frontdoor config)... why wouldn't you want to reserve that share/name? If it were trying to re-create the same ephemeral share every time with a reserved name, you're not guaranteed that it will be available.