zrok/docs/guides/docker-share/docker_public_share_guide.md

sidebar_position	sidebar_label
10	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 public URL thats temporary or reserved (reusable).

Walkthrough Video

Before You Begin

To follow this guide you will need Docker and the Docker Compose plugin for running docker compose commands in your terminal.

Temporary or Reserved Public Share

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.

1. Make a folder on your computer to use as a Docker Compose project for your zrok public share.
2. In your terminal, change directory to the newly-created project folder.
3. Download either the temporary public share project file or the reserved public share project file into the project folder.
4. 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:

ZROK_ENABLE_TOKEN="8UL9-48rN0ua"

1. Set the zrok API endpoint if self-hosting zrok. Skip this if using zrok.io.

ZROK_API_ENDPOINT="https://zrok.example.com"

1. Run the Compose project to start sharing the built-in demo web server.

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 be graphed.

docker compose logs zrok-share

zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/

This concludes sharing the demo web server. Read on to learn how to pivot to sharing any web server 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 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.

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. This applies to both temporary and reserved public shares.

ZROK_OAUTH_PROVIDER="github"

Customize Temporary Public Share

1. Create a file compose.override.yml. This example demonstrates sharing a static HTML directory /tmp/html from the Docker host's filesystem.

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.

docker compose up --force-recreate --detach

1. Get the new tempoary public share URL for the zrok-share container.

docker compose logs zrok-share

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.

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.

docker compose up --force-recreate --detach

1. Recall the reserved share URL from the log.

docker compose logs zrok-share

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.

docker compose down --volumes