<titledata-rh="true">zrok frontdoor | Zrok</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.zrok.io/docs/guides/frontdoor/"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="zrok frontdoor | Zrok"><metadata-rh="true"name="description"content="zrok frontdoor is the heavy-duty front door to your app or site. It makes your website or app available to your online audience through the shield of zrok.io's hardened, managed frontends."><metadata-rh="true"property="og:description"content="zrok frontdoor is the heavy-duty front door to your app or site. It makes your website or app available to your online audience through the shield of zrok.io's hardened, managed frontends."><linkdata-rh="true"rel="icon"href="/img/space-ziggy.png"><linkdata-rh="true"rel="canonical"href="https://docs.zrok.io/docs/guides/frontdoor/"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/frontdoor/"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/guides/frontdoor/"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://CO73R59OLO-dsn.algolia.net"crossorigin="anonymous"><linkrel="preconnect"href="https://www.google-analytics.com">
<iframewidth="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"></iframe>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="overview">Overview<ahref="#overview"class="hash-link"aria-label="Direct link to Overview"title="Direct link to Overview"></a></h2>
<p>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 <code>zrok.io</code> frontend, you're using <strong>zrok frontdoor</strong>. <code>zrok.io</code> is zrok-as-a-service by NetFoundry, the team behind OpenZiti. You need a free account to use <strong>zrok frontdoor</strong>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="choose-your-os">Choose your OS<ahref="#choose-your-os"class="hash-link"aria-label="Direct link to Choose your OS"title="Direct link to Choose your OS"></a></h2>
<p>Choose between installing the Linux package or running zrok with Docker (Linux, macOS, or Windows).</p>
<divclass="tabs-container tabList__CuJ"><ulrole="tablist"aria-orientation="horizontal"class="tabs"><lirole="tab"tabindex="0"aria-selected="true"class="tabs__item tabItem_LNqP tabs__item--active">Linux</li><lirole="tab"tabindex="-1"aria-selected="false"class="tabs__item tabItem_LNqP">macOS</li><lirole="tab"tabindex="-1"aria-selected="false"class="tabs__item tabItem_LNqP">Windows</li></ul><divclass="margin-top--md"><divrole="tabpanel"class="tabItem_Ymn6"><p>On Linux, zrok frontdoor is implemented natively as a system service provided by the <code>zrok-share</code> DEB or RPM package.</p><p>If you'd prefer to run zrok in Docker instead of installing the package then you can follow the Docker instructions. With Docker, the steps are the same for Linux, <ahref="/docs/guides/frontdoor/?os=Mac+OS">macOS</a>, and <ahref="/docs/guides/frontdoor/?os=Windows">Windows</a>.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="goal">Goal<ahref="#goal"class="hash-link"aria-label="Direct link to Goal"title="Direct link to Goal"></a></h2>
<p>Proxy a reserved public subdomain to a backend target with an always-on Linux system service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="how-it-works">How it Works<ahref="#how-it-works"class="hash-link"aria-label="Direct link to How it Works"title="Direct link to How it Works"></a></h2>
<p>The <code>zrok-share</code> package creates a <code>zrok-share.service</code> unit in systemd. The administrator edits the service's configuration file to specify the:</p>
<ol>
<li>zrok environment enable token</li>
<li>target URL or files to be shared and backend mode, e.g. <code>proxy</code></li>
<li>authentication options, if wanted</li>
</ol>
<p>When the service starts it will:</p>
<ol>
<li>enable the zrok environment unless <code>/var/lib/zrok-share/.zrok/environment.json</code> exists</li>
<li>reserve a public subdomain for the service unless <code>/var/lib/zrok-share/.zrok/reserved.json</code> exists</li>
<li>start sharing the target specified as <code>ZROK_TARGET</code> in the environment file</li>
</ol>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="installation">Installation<ahref="#installation"class="hash-link"aria-label="Direct link to Installation"title="Direct link to Installation"></a></h2>
<p>Set up <code>zrok</code>'s Linux package repository by following <ahref="/docs/guides/install/linux/#install-zrok-from-the-repository">the Linux install guide</a>, or run this one-liner to complete the repo setup and install packages.</p>
<p>If you set up the repository by following the guide, then also install the <code>zrok-share</code> package. This package provides the systemd service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="enable">Enable<ahref="#enable"class="hash-link"aria-label="Direct link to Enable"title="Direct link to Enable"></a></h2>
<p>Save the enable token from the zrok console in the configuration file.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="name-your-share">Name your Share<ahref="#name-your-share"class="hash-link"aria-label="Direct link to Name your Share"title="Direct link to Name your Share"></a></h2>
<p>This unique name becomes part of the domain name of the share, e.g. <code>https://my-prod-app.in.zrok.io</code>. A random name is generated if you don't specify one.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="use-cases">Use Cases<ahref="#use-cases"class="hash-link"aria-label="Direct link to Use Cases"title="Direct link to Use Cases"></a></h2>
<p>You may change the target for the current backend mode, e.g. <code>proxy</code>, by editing the configuration file and restarting the service. The reserved subdomain will remain the same.</p>
<p>You may switch between backend modes or change authentication options by deleting <code>/var/lib/zrok-share/.zrok/reserved.json</code> and restarting the service. A new subdomain will be reserved.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="proxy-a-web-server">Proxy a Web Server<ahref="#proxy-a-web-server"class="hash-link"aria-label="Direct link to Proxy a Web Server"title="Direct link to Proxy a Web Server"></a></h3>
<p>Proxy a reserved subdomain to an existing web server. The web server could be on a private network or on the same host as zrok.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="serve-static-files">Serve Static Files<ahref="#serve-static-files"class="hash-link"aria-label="Direct link to Serve Static Files"title="Direct link to Serve Static Files"></a></h3>
<p>Run zrok's embedded web server to serve the files in a directory. If there's an <code>index.html</code> file in the directory then visitors will see that web page in their browser, otherwise they'll see a generated index of the files. The directory must be readable by 'other', e.g. <code>chmod -R o+rX /var/www/html</code>.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="caddy-server">Caddy Server<ahref="#caddy-server"class="hash-link"aria-label="Direct link to Caddy Server"title="Direct link to Caddy Server"></a></h3>
<p>Use zrok's built-in Caddy server to serve static files or as a reverse proxy to multiple web servers with various HTTP routes or as a load-balanced set. A sample Caddyfile is available in the path shown.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="network-drive">Network Drive<ahref="#network-drive"class="hash-link"aria-label="Direct link to Network Drive"title="Direct link to Network Drive"></a></h3>
<p>This uses zrok's <code>drive</code> backend mode to serve a directory of static files as a virtual network drive. The directory must be readable by 'other', e.g. <code>chmod -R o+rX /usr/share/doc</code>.</p>
<p><ahref="https://blog.openziti.io/zrok-drives-an-early-preview"target="_blank"rel="noopener noreferrer">Learn more about this feature in this blog post</a>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="authentication">Authentication<ahref="#authentication"class="hash-link"aria-label="Direct link to Authentication"title="Direct link to Authentication"></a></h2>
<p>You can limit access to certain email addresses with OAuth or require a password.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="oauth">OAuth<ahref="#oauth"class="hash-link"aria-label="Direct link to OAuth"title="Direct link to OAuth"></a></h3>
<p>You can require that visitors authenticate with an email address that matches at least one of the suffixes you specify. Add the following to the configuration file.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="password">Password<ahref="#password"class="hash-link"aria-label="Direct link to Password"title="Direct link to Password"></a></h3>
<p>Enable HTTP basic authentication by adding the following to the configuration file.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="start-the-service">Start the Service<ahref="#start-the-service"class="hash-link"aria-label="Direct link to Start the Service"title="Direct link to Start the Service"></a></h2>
<p>Start the service, and check the zrok console or the service log for the reserved subdomain.</p>
<divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockTitle_Ktv7">run now and at startup</div><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">sudo systemctl enable --now zrok-share.service</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="compatibility">Compatibility<ahref="#compatibility"class="hash-link"aria-label="Direct link to Compatibility"title="Direct link to Compatibility"></a></h2>
<p>The Linux distribution must have a package manager that understands the <code>.deb</code> or <code>.rpm</code> format and be running systemd v232 or newer. The service was tested with:</p>
<ul>
<li>Ubuntu 20.04, 22.04, 23.04</li>
<li>Debian 11 12</li>
<li>Rocky 8, 9</li>
<li>Fedora 37, 38</li>
</ul>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="package-contents">Package Contents<ahref="#package-contents"class="hash-link"aria-label="Direct link to Package Contents"title="Direct link to Package Contents"></a></h2>
<p>The files included in the <code>zrok-share</code> package are sourced <ahref="https://github.com/openziti/zrok/tree/main/nfpm"target="_blank"rel="noopener noreferrer">here in GitHub</a>.</p></div><divrole="tabpanel"class="tabItem_Ymn6"hidden=""><p>On macOS, zrok frontdoor is implemented as a Docker Compose project which reserves a public subdomain for your website or service.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="goal">Goal<ahref="#goal"class="hash-link"aria-label="Direct link to Goal"title="Direct link to Goal"></a></h2>
<p>Proxy a reserved public subdomain to a backend target with an always-on Docker Compose service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="how-it-works">How it Works<ahref="#how-it-works"class="hash-link"aria-label="Direct link to How it Works"title="Direct link to How it Works"></a></h2>
<p>The Docker Compose project uses your zrok account token to reserve a public subdomain and keep sharing the backend
target.</p>
<p>When the project runs it will:</p>
<ol>
<li>enable a zrok environment unless <code>/mnt/.zrok/environment.json</code> exists in the <code>zrok_env</code> volume</li>
<li>reserve a public subdomain for the service unless <code>/mnt/.zrok/reserved.json</code> exists</li>
<li>start sharing the target specified in the <code>ZROK_TARGET</code> environment variable</li>
</ol>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="create-the-docker-project">Create the Docker Project<ahref="#create-the-docker-project"class="hash-link"aria-label="Direct link to Create the Docker Project"title="Direct link to Create the Docker Project"></a></h2>
<p>Make a folder on your computer to use as a Docker Compose project for your zrok public share with a reserved subdomain and switch to the new directory in your terminal.</p>
</li>
<li>
<p>Download <ahref="/zrok-public-reserved/compose.yml"target="_blank"rel="noopener noreferrer">the reserved public share <code>compose.yml</code> project file</a> into the same directory.</p>
</li>
<li>
<p>Copy your zrok account's enable token from the zrok web console to your clipboard and paste it in a file named <code>.env</code> in the same folder like this:</p>
<p>This unique name becomes part of the domain name of the share, e.g. <code>https://my-prod-app.in.zrok.io</code>. A random name is generated if you don't specify one.</p>
<p>Run the Compose project to start sharing the built-in demo web server. Be sure to <code>--detach</code> so the project runs in the background if you want it to auto-restart when your computer reboots.</p>
<p>Get the public share URL from the output of the <code>zrok-share</code> service or by peeking in the zrok console where the share will appear in the graph.</p>
<p>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.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="proxy-any-web-server">Proxy Any Web Server<ahref="#proxy-any-web-server"class="hash-link"aria-label="Direct link to Proxy Any Web Server"title="Direct link to Proxy Any Web Server"></a></h2>
<p>The simplest way to share your existing HTTP server is to set <code>ZROK_TARGET</code> (e.g. <code>https://example.com</code>) in the environment of the <code>docker compose up</code> command. When you restart the share will auto-configure for that URL.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="require-authentication">Require Authentication<ahref="#require-authentication"class="hash-link"aria-label="Direct link to Require Authentication"title="Direct link to Require Authentication"></a></h2>
<p>You can require a password or an OAuth login with certain email addresses.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="oauth-email">OAuth Email<ahref="#oauth-email"class="hash-link"aria-label="Direct link to OAuth Email"title="Direct link to OAuth Email"></a></h3>
<p>You can allow specific email addresses or an email domain by setting <code>ZROK_OAUTH_PROVIDER</code> to <code>github</code> or <code>google</code> and
<code>ZROK_SHARE_OPTS</code> to specify additional command-line options to <code>zrok reserve public</code>. Read more about the OAuth
features in <ahref="https://blog.openziti.io/the-zrok-oauth-public-frontend"target="_blank"rel="noopener noreferrer">this blog post</a>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="caddy-is-powerful">Caddy is Powerful<ahref="#caddy-is-powerful"class="hash-link"aria-label="Direct link to Caddy is Powerful"title="Direct link to Caddy is Powerful"></a></h2>
<p>The reserved public share project uses zrok's default backend mode, <code>proxy</code>. Another backend mode, <code>caddy</code>, accepts a path to <ahref="https://caddyserver.com/docs/caddyfile"target="_blank"rel="noopener noreferrer">a Caddyfile</a> as the value of <code>ZROK_TARGET</code> (<ahref="https://github.com/openziti/zrok/tree/main/etc/caddy"target="_blank"rel="noopener noreferrer">zrok Caddyfile examples</a>).</p>
<p>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 <code>caddy</code> reduces the risk that you'll have to share a new frontend URL with your users.</p>
<p>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.</p>
<p>Create a file <code>compose.override.yml</code>. This example adds two <code>httpbin</code> containers for load balancing, and mounts the Caddyfile into the container.</p>
<p>If you prefer to keep using the same zrok environment with the new share then delete <code>/mnt/.zrok/reserved.json</code> instead of the entire volume.</p>
</ol></div><divrole="tabpanel"class="tabItem_Ymn6"hidden=""><p>On Windows, zrok frontdoor is implemented as a Docker Compose project which reserves a public subdomain for your website or service.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="goal">Goal<ahref="#goal"class="hash-link"aria-label="Direct link to Goal"title="Direct link to Goal"></a></h2>
<p>Proxy a reserved public subdomain to a backend target with an always-on Docker Compose service.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="how-it-works">How it Works<ahref="#how-it-works"class="hash-link"aria-label="Direct link to How it Works"title="Direct link to How it Works"></a></h2>
<p>The Docker Compose project uses your zrok account token to reserve a public subdomain and keep sharing the backend
target.</p>
<p>When the project runs it will:</p>
<ol>
<li>enable a zrok environment unless <code>/mnt/.zrok/environment.json</code> exists in the <code>zrok_env</code> volume</li>
<li>reserve a public subdomain for the service unless <code>/mnt/.zrok/reserved.json</code> exists</li>
<li>start sharing the target specified in the <code>ZROK_TARGET</code> environment variable</li>
</ol>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="create-the-docker-project">Create the Docker Project<ahref="#create-the-docker-project"class="hash-link"aria-label="Direct link to Create the Docker Project"title="Direct link to Create the Docker Project"></a></h2>
<p>Make a folder on your computer to use as a Docker Compose project for your zrok public share with a reserved subdomain and switch to the new directory in your terminal.</p>
</li>
<li>
<p>Download <ahref="/zrok-public-reserved/compose.yml"target="_blank"rel="noopener noreferrer">the reserved public share <code>compose.yml</code> project file</a> into the same directory.</p>
</li>
<li>
<p>Copy your zrok account's enable token from the zrok web console to your clipboard and paste it in a file named <code>.env</code> in the same folder like this:</p>
<p>This unique name becomes part of the domain name of the share, e.g. <code>https://my-prod-app.in.zrok.io</code>. A random name is generated if you don't specify one.</p>
<p>Run the Compose project to start sharing the built-in demo web server. Be sure to <code>--detach</code> so the project runs in the background if you want it to auto-restart when your computer reboots.</p>
<p>Get the public share URL from the output of the <code>zrok-share</code> service or by peeking in the zrok console where the share will appear in the graph.</p>
<p>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.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="proxy-any-web-server">Proxy Any Web Server<ahref="#proxy-any-web-server"class="hash-link"aria-label="Direct link to Proxy Any Web Server"title="Direct link to Proxy Any Web Server"></a></h2>
<p>The simplest way to share your existing HTTP server is to set <code>ZROK_TARGET</code> (e.g. <code>https://example.com</code>) in the environment of the <code>docker compose up</code> command. When you restart the share will auto-configure for that URL.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="require-authentication">Require Authentication<ahref="#require-authentication"class="hash-link"aria-label="Direct link to Require Authentication"title="Direct link to Require Authentication"></a></h2>
<p>You can require a password or an OAuth login with certain email addresses.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="oauth-email">OAuth Email<ahref="#oauth-email"class="hash-link"aria-label="Direct link to OAuth Email"title="Direct link to OAuth Email"></a></h3>
<p>You can allow specific email addresses or an email domain by setting <code>ZROK_OAUTH_PROVIDER</code> to <code>github</code> or <code>google</code> and
<code>ZROK_SHARE_OPTS</code> to specify additional command-line options to <code>zrok reserve public</code>. Read more about the OAuth
features in <ahref="https://blog.openziti.io/the-zrok-oauth-public-frontend"target="_blank"rel="noopener noreferrer">this blog post</a>.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="caddy-is-powerful">Caddy is Powerful<ahref="#caddy-is-powerful"class="hash-link"aria-label="Direct link to Caddy is Powerful"title="Direct link to Caddy is Powerful"></a></h2>
<p>The reserved public share project uses zrok's default backend mode, <code>proxy</code>. Another backend mode, <code>caddy</code>, accepts a path to <ahref="https://caddyserver.com/docs/caddyfile"target="_blank"rel="noopener noreferrer">a Caddyfile</a> as the value of <code>ZROK_TARGET</code> (<ahref="https://github.com/openziti/zrok/tree/main/etc/caddy"target="_blank"rel="noopener noreferrer">zrok Caddyfile examples</a>).</p>
<p>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 <code>caddy</code> reduces the risk that you'll have to share a new frontend URL with your users.</p>
<p>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.</p>
<p>Create a file <code>compose.override.yml</code>. This example adds two <code>httpbin</code> containers for load balancing, and mounts the Caddyfile into the container.</p>
<p>If you prefer to keep using the same zrok environment with the new share then delete <code>/mnt/.zrok/reserved.json</code> instead of the entire volume.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="concepts">Concepts<ahref="#concepts"class="hash-link"aria-label="Direct link to Concepts"title="Direct link to Concepts"></a></h2>
