diff --git a/docs/guides/custom-domains/_category_.json b/docs/guides/custom-domains/_category_.json new file mode 100644 index 00000000..694c0ea5 --- /dev/null +++ b/docs/guides/custom-domains/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Custom Domains", + "position": 120, + "link": { + "type": "doc", + "id": "guides/custom-domains/index" + } +} diff --git a/docs/guides/custom-domains/images/myzrok_add_a_record.png b/docs/guides/custom-domains/images/myzrok_add_a_record.png new file mode 100644 index 00000000..751fe3b1 Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_add_a_record.png differ diff --git a/docs/guides/custom-domains/images/myzrok_add_cname.png b/docs/guides/custom-domains/images/myzrok_add_cname.png new file mode 100644 index 00000000..d079c2a1 Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_add_cname.png differ diff --git a/docs/guides/custom-domains/images/myzrok_add_domain.png b/docs/guides/custom-domains/images/myzrok_add_domain.png new file mode 100644 index 00000000..8b3574ad Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_add_domain.png differ diff --git a/docs/guides/custom-domains/images/myzrok_domains_page.png b/docs/guides/custom-domains/images/myzrok_domains_page.png new file mode 100644 index 00000000..170e6a8e Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_domains_page.png differ diff --git a/docs/guides/custom-domains/images/myzrok_finalize.png b/docs/guides/custom-domains/images/myzrok_finalize.png new file mode 100644 index 00000000..09008be5 Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_finalize.png differ diff --git a/docs/guides/custom-domains/images/myzrok_verify_dns.png b/docs/guides/custom-domains/images/myzrok_verify_dns.png new file mode 100644 index 00000000..bb689c9d Binary files /dev/null and b/docs/guides/custom-domains/images/myzrok_verify_dns.png differ diff --git a/docs/guides/custom-domains/images/zrok_status.png b/docs/guides/custom-domains/images/zrok_status.png new file mode 100644 index 00000000..d562d5dc Binary files /dev/null and b/docs/guides/custom-domains/images/zrok_status.png differ diff --git a/docs/guides/custom-domains/index.mdx b/docs/guides/custom-domains/index.mdx new file mode 100644 index 00000000..340f97a5 --- /dev/null +++ b/docs/guides/custom-domains/index.mdx @@ -0,0 +1,97 @@ +--- +title: Custom Domains +--- + +## Overview +[myzrok.io](https://myzrok.io) is a hosted zrok-as-a-service offering that provides a way for you bring a custom DNS name for zrok shares. +For example, let's say you own the domain `foo.example.io`, you can leverage zrok custom domains to +create ephemeral shares such as: `https://vw8jbg4ijz5g.foo.example.io` +or [reserved shares](/concepts/sharing-reserved.md) such as `https://myshare.foo.example.io`. + +Custom domains require a Pro subscription with [myzrok.io](https://myzrok.io). +If you don't already have an account, you can sign up for one [here](https://myzrok.io). + +[myzrok.io](https://myzrok.io) provides a guided setup with just a few easy steps! + +1. Bring your own custom domain name +2. Create DNS validation records and a CNAME record +3. Wait for zrok to validate your records and finalize configuration +4. Start sharing! + +Detailed setup instructions are documented below. + +### Prerequisites +:::note +In order to create a custom domain in zrok, **you must already own the domain you want to use.** +::: + +During the setup process you will need to create DNS records to validate ownership and to allow a certiicate to be issued +on behalf of your domain. Once you have your domain registered, you can begin the process of setting up your custom +domain with zrok! + +### Create Your Custom Domain + +Log into the myzrok Console and access the domains page by clicking on the globe icon in the left navigation menu. + +![myzrok_domains_page](images/myzrok_domains_page.png) + +Custom domains require a Pro subscription in [myzrok.io](https://myzrok.io) + +Click the CREATE button on the top right of the page to get started. +When you click the create button you’ll be presented with a form to allow you to enable your custom domain. +Enter your domain into the form field and click CREATE. This will begin the process for setting up your custom domain. +A new managed TLS certificate will be created to host traffic on your domain's behalf. + +![myzrok_add_domain](images/myzrok_add_domain.png) + +This may take a few minutes. +You may close the form at this time and come back when your domain is *pending validation.* +Once your certificate is ready, you’ll be presented with instructions on how to set up your DNS records. + +### Creating DNS Records + +zrok will host and manage a TLS certificate for the custom domain on your behalf. +This process requires a DNS validation record to be created in order to prove ownership of the domain. +Follow the prompts in the UI to create a CNAME DNS record with the name and value specified in the UI. + +![myzrok_add_cname](images/myzrok_add_cname.png) + +Next, create an A record to direct all DNS requests for your domain to a set of static IPs that are hosted by zrok. + +![myzrok_add_a_record](images/myzrok_add_a_record.png) + +After you’ve created your records, you can verify that they are configured properly using the instructions provided in the form. + +![myzrok_verify_dns](images/myzrok_verify_dns.png) + +Once you have created your DNS records, it will take zrok a few minutes to validate that they exist. +You can safely close the form until your certificate has been issued. + +### Finalizing Your Custom Domain + +After your records have been validated and your certificate has been issued, click the Finalize button within 72 hours to complete your custom domain setup. + +![myzrok_finalize](images/myzrok_finalize.png) + +From here, myzrok.io will complete the last few steps of creating your custom domain. +This should only take a minute, but if you need to close the form you can find the instructions on how to share your frontend when you return. + +### Start Sharing! +Once the Finalize stage has completed, you can start sharing with your custom DNS! + +In order to create shares that utilize your custom DNS, you will need to specify the `--frontend` flag when creating a share, +or update your environment configuration to use this new frontend by default. + +``` +zrok share public --frontend foo-example--goPIhgtJtz +``` + +You can set the custom frontend as the environment default by running: + +``` +zrok config set defaultFrontend foo-example--goPIhgtJtz +``` + +To validate which frontend is being used, use the `zrok status` command, which will identify the default frontend being used: + +![zrok_status](images/zrok_status.png)