Bring your own DNS domain

Intro

When you create a new socket, it will get a deterministic name following this naming scheme: <socket_name>-<org_name>.border0.io. This works for many cases, but there are scenarios where you may want to use your own domain name. Perhaps something like example.com.

In this how-to, we'll look at how to achieve that by bringing your DNS domain name into your Border0 organization. After you bring in your own custom domain into your organization, all sockets in the organization will be available as <socket_name>.<customdomain>. For example, you could bring the domain example.com; if you have a socket called wiki, that will become available as wiki.example.com.

There are really only two steps that are needed to Bring Your Own Domain, and it's just 2 minutes of work.

  1. Update your DNS setting for the domain you're bringing in.
  2. Add the domain name to the Border0 organization.

Sounds pretty simple right, lets' dive in!

πŸ“˜

The "bring your own" domain feature is a premium feature. If you don't have a premium subscription, please contact us ([email protected]).

1 - Add CNAME DNS entries

To start, you need to create two CNAME records in the domain.

  1. You need a wildcard (*) CNAME record that points to the organization subdomain (<org_name>.border0.io.).

  2. And we require a CNAME for the certificate validation _acme-challenge that points to the acme.border0.io domain <own_domain>.<org_name>.acme.border0.io.

This is required, so traffic is routed to our global network, and we can create the certificates for your domain.
The example below shows a wildcard CNAME for the example.com custom domain pointing to the organization subdomain exampleorg.border0.io. and a _acme-challenge record in the example.com domain pointing to the acme.border0.io domain.

example.com DNS zone:

NameTypeValue
*CNAMEexampleorg.border0.io.
_acme-challengeCNAMEexample.com.exampleorg.acme.border0.io.

To verify the CNAME records, you can use dig (or any other DNS lookup tool).
The output should look like this.

$ dig wiki.example.com
<SNIP>
;; ANSWER SECTION:
wiki.example.com. 3600 IN CNAME exampleorg.border0.io.
exampleorg.border0.io. 300 IN A 15.197.134.180
$ dig _acme-challenge.example.com
<SNIP>
;; ANSWER SECTION:
_acme-challenge.example.com. 3600 IN CNAME example.com.exampleorg.acme.border0.io.

You must complete the DNS changes first before continuing with step 2. Without the DNS changes in place, the next steps will not succeed.

2- Add the Custom Domain name to your Organization

Now that the CNAME records exist, we can add the custom domain name to the organization. This can be done in the border0 portal. Only users with the admin role can add custom domains to the organization.

In the portal, click on Organization Settings on the left menu, and then select the Domains tab.

Now you can use the action button to add a new domain.

1756

You can now also select the Make this the default domain option. If you enable this, the default domain for all sockets (current and new) in the organization will change to this domain. Don't worry; nothing will break; the sockets will also be available under the original organization subdomain<socket_name>-<org_name>.border0.io.

Multiple domains can be added, but you can only have one default domain. You can always specify which domain you want to set as the default domain under the Domains tab.

You can also use the border0 CLI to manage the organization's custom domains. For this, use the following
command border0 organization domain

$ border0 organization domain

manage organization domains

Usage:
  border0 organization domain [command]

Available Commands:
  add            Add organization domain
  list           list organization domains
  remove         Remove organization domain
  update         Update organization domain

πŸ‘

That's it!

Congrats, that's it! Your Border0 services are now available with your own custom DNS names! That was easy, right?!

3- Advanced: Configure your socket to use the domain name

Once a domain has been added, you can use the domain option in the socket configuration to specify the domain you want to use for that socket. This is useful when you have multiple custom domains.

1992

In the border0 CLI you can use the -o option to specify the domain name.

border0 socket create -n wiki -o example.com