zrok/assets/js/2e812224.68c0f545.js

"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([[76],{3905:(e,t,r)=>{r.d(t,{Zo:()=>c,kt:()=>h});var a=r(7294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function i(e){for(var t=1;t<arguments.length;t++){var r=null!=arguments[t]?arguments[t]:{};t%2?n(Object(r),!0).forEach((function(t){o(e,t,r[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):n(Object(r)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(r,t))}))}return e}function l(e,t){if(null==e)return{};var r,a,o=function(e,t){if(null==e)return{};var r,a,o={},n=Object.keys(e);for(a=0;a<n.length;a++)r=n[a],t.indexOf(r)>=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(a=0;a<n.length;a++)r=n[a],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var p=a.createContext({}),s=function(e){var t=a.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},c=function(e){var t=s(e.components);return a.createElement(p.Provider,{value:t},e.children)},m="mdxType",u={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},d=a.forwardRef((function(e,t){var r=e.components,o=e.mdxType,n=e.originalType,p=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),m=s(r),d=o,h=m["".concat(p,".").concat(d)]||m[d]||u[d]||n;return r?a.createElement(h,i(i({ref:t},c),{},{components:r})):a.createElement(h,i({ref:t},c))}));function h(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var n=r.length,i=new Array(n);i[0]=d;var l={};for(var p in t)hasOwnProperty.call(t,p)&&(l[p]=t[p]);l.originalType=e,l[m]="string"==typeof e?e:o,i[1]=l;for(var s=2;s<n;s++)i[s]=r[s];return a.createElement.apply(null,i)}return a.createElement.apply(null,r)}d.displayName="MDXCreateElement"},7080:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>m,frontMatter:()=>n,metadata:()=>l,toc:()=>s});var a=r(7462),o=(r(7294),r(3905));const n={sidebar_position:10,sidebar_label:"Public Share"},i="Docker Public Share",l={unversionedId:"guides/docker-share/docker_public_share_guide",id:"guides/docker-share/docker_public_share_guide",title:"Docker Public Share",description:"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).",source:"@site/../docs/guides/docker-share/docker_public_share_guide.md",sourceDirName:"guides/docker-share",slug:"/guides/docker-share/docker_public_share_guide",permalink:"/docs/guides/docker-share/docker_public_share_guide",draft:!1,editUrl:"https://github.com/openziti/zrok/blob/main/docs/../docs/guides/docker-share/docker_public_share_guide.md",tags:[],version:"current",sidebarPosition:10,frontMatter:{sidebar_position:10,sidebar_label:"Public Share"},sidebar:"tutorialSidebar",previous:{title:"Docker Share",permalink:"/docs/category/docker-share"},next:{title:"Private Share",permalink:"/docs/guides/docker-share/docker_private_share_guide"}},p={},s=[{value:"Walkthrough Video",id:"walkthrough-video",level:2},{value:"Before You Begin",id:"before-you-begin",level:2},{value:"Temporary or Reserved Public Share",id:"temporary-or-reserved-public-share",level:2},{value:"Proxy Any Web Server",id:"proxy-any-web-server",level:2},{value:"Require Authentication",id:"require-authentication",level:2},{value:"Customize Temporary Public Share",id:"customize-temporary-public-share",level:2},{value:"Customize Reserved Public Share",id:"customize-reserved-public-share",level:2},{value:"Destroy the zrok Environment",id:"destroy-the-zrok-environment",level:2}],c={toc:s};function m(e){let{components:t,...r}=e;return(0,o.kt)("wrapper",(0,a.Z)({},c,r,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"docker-public-share"},"Docker Public Share"),(0,o.kt)("p",null,"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)."),(0,o.kt)("h2",{id:"walkthrough-video"},"Walkthrough Video"),(0,o.kt)("iframe",{width:"100%",height:"315",src:"https://www.youtube.com/embed/ycov--9ZtB4",title:"YouTube video player",frameborder:"0",allow:"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",allowfullscreen:!0}),(0,o.kt)("h2",{id:"before-you-begin"},"Before You Begin"),(0,o.kt)("p",null,"To follow this guide you will need ",(0,o.kt)("a",{parentName:"p",href:"https://docs.docker.com/get-docker/"},"Docker")," and ",(0,o.kt)("a",{parentName:"p",href:"https://docs.docker.com/compose/install/"},"the Docker Compose plugin")," for running ",(0,o.kt)("inlineCode",{parentName:"p"},"docker compose")," commands in your terminal."),(0,o.kt)("h2",{id:"temporary-or-reserved-public-share"},"Temporary or Reserved Public Share"),(0,o.kt)("p",null,"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."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Make a folder on your computer to use as a Docker Compose project for your zrok public share.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"In your terminal, change directory to the newly-created project folder.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Download either ",(0,o.kt)("a",{parentName:"p",href:"pathname:///zrok-public-share/compose.yml"},"the temporary public share project file")," or ",(0,o.kt)("a",{parentName:"p",href:"pathname:///zrok-public-reserved/compose.yml"},"the reserved public share project file")," into the project folder.")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named ",(0,o.kt)("inlineCode",{parentName:"p"},".env")," in the same folder like this:"),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env"',title:'".env"'},'ZROK_ENABLE_TOKEN="8UL9-48rN0ua"\n'))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Set the zrok API endpoint if self-hosting zrok. Skip this if using zrok.io."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env"',title:'".env"'},'ZROK_API_ENDPOINT="https://zrok.example.com"\n'))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Run the Compose project to start sharing the built-in demo web server."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose up --detach\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Get the public share URL from the output of the ",(0,o.kt)("inlineCode",{parentName:"p"},"zrok-share")," service or by peeking in the zrok console where the share will be graphed."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose logs zrok-share\n")),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-buttonless",metastring:'title="Output"',title:'"Output"'},"zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/\n")))),(0,o.kt)("p",null,"This concludes sharing the demo web server. Read on to learn how to pivot to sharing any web server leveraging additional zrok backend modes."),(0,o.kt)("h2",{id:"proxy-any-web-server"},"Proxy Any Web Server"),(0,o.kt)("p",null,"The simplest way to share your web server is to set ",(0,o.kt)("inlineCode",{parentName:"p"},"ZROK_BACKEND")," (e.g. ",(0,o.kt)("inlineCode",{parentName:"p"},"https://example.com"),") in the environment of the ",(0,o.kt)("inlineCode",{parentName:"p"},"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."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env"',title:'".env"'},'ZROK_BACKEND="http://example.com:8080"\n')),(0,o.kt)("h2",{id:"require-authentication"},"Require Authentication"),(0,o.kt)("p",null,"You can require authentication for your public share by setting ",(0,o.kt)("inlineCode",{parentName:"p"},"ZROK_OAUTH_PROVIDER")," to ",(0,o.kt)("inlineCode",{parentName:"p"},"github")," or ",(0,o.kt)("inlineCode",{parentName:"p"},"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 ",(0,o.kt)("a",{parentName:"p",href:"https://blog.openziti.io/the-zrok-oauth-public-frontend"},"this blog post"),". This applies to both temporary and reserved public shares."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash",metastring:'title=".env"',title:'".env"'},'ZROK_OAUTH_PROVIDER="github"\n')),(0,o.kt)("h2",{id:"customize-temporary-public-share"},"Customize Temporary Public Share"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create a file ",(0,o.kt)("inlineCode",{parentName:"p"},"compose.override.yml"),". This example demonstrates sharing a static HTML directory ",(0,o.kt)("inlineCode",{parentName:"p"},"/tmp/html")," from the Docker host's filesystem."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="compose.override.yml"',title:'"compose.override.yml"'},"services:\n  zrok-share:\n    command: share public --headless --backend-mode web /tmp/html\n    volumes:\n      - /tmp/html:/tmp/html\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Re-run the project to load the new configuration."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose up --force-recreate --detach\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Get the new tempoary public share URL for the ",(0,o.kt)("inlineCode",{parentName:"p"},"zrok-share")," container."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose logs zrok-share\n")),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-buttonless",metastring:'title="Output"',title:'"Output"'},"zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/\n")))),(0,o.kt)("h2",{id:"customize-reserved-public-share"},"Customize Reserved Public Share"),(0,o.kt)("p",null,"The reserved public share project uses zrok's ",(0,o.kt)("inlineCode",{parentName:"p"},"caddy")," mode. Caddy accepts configuration as a Caddyfile that is mounted into the container (",(0,o.kt)("a",{parentName:"p",href:"https://github.com/openziti/zrok/tree/main/etc/caddy"},"zrok Caddyfile examples"),")."),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create a Caddyfile. This example demonstrates proxying two HTTP servers with a weighted round-robin load balancer."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-console",metastring:'title="Caddyfile"',title:'"Caddyfile"'},"http:// {\n  # zrok requires this bind address template\n  bind {{ .ZrokBindAddress }}\n  reverse_proxy /* {\n    to http://httpbin1:8080 http://httpbin2:8080\n    lb_policy weighted_round_robin 3 2\n  }\n}\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create a file ",(0,o.kt)("inlineCode",{parentName:"p"},"compose.override.yml"),". This example adds two ",(0,o.kt)("inlineCode",{parentName:"p"},"httpbin")," containers for Caddy load balance, and masks the default Caddyfile with our custom one."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-yaml",metastring:'title="compose.override.yml"',title:'"compose.override.yml"'},"services:\n  httpbin1:\n    image: mccutchen/go-httpbin  # 8080/tcp\n  httpbin2:\n    image: mccutchen/go-httpbin  # 8080/tcp\n  zrok-share:\n    volumes:\n      - ./Caddyfile:/mnt/.zrok/Caddyfile\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Re-run the project to load the new configuration."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose up --force-recreate --detach\n"))),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Recall the reserved share URL from the log."),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose logs zrok-share\n")),(0,o.kt)("pre",{parentName:"li"},(0,o.kt)("code",{parentName:"pre",className:"language-buttonless",metastring:'title="Output"',title:'"Output"'},"INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/\n")))),(0,o.kt)("h2",{id:"destroy-the-zrok-environment"},"Destroy the zrok Environment"),(0,o.kt)("p",null,"This destroys the Docker volumes containing the zrok environment secrets. The zrok environment can also be destroyed in the web console."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-bash"},"docker compose down --volumes\n")))}m.isMDXComponent=!0}}]);