[Support Guide] Best practices for using your customers' hostnames on the Netlify site you build for them

Last reviewed by Netlify Support staff September 2023

We understand that many Netlify customers build websites for their own customers and need hostnames tailored to each user. This guide will explain the possibilities for hosting content like that in several different ways and demonstrate the tradeoffs between choosing one of these methodologies.

Let’s start off by covering the prerequisites that will set you up for success:

  • You will need to have a valid SSL certificate for all hostnames you will serve, as Netlify only serves HTTPS (encrypted) web traffic.
  • You should be aware that based on our past experience, some of your customers will likely struggle to configure their DNS correctly, and thus you will need to provide tech support to them as they configure this hostname. We have extensive documentation that you can share with them or repurpose, but it is still the case that many less savvy teams have trouble configuring DNS and will require your help with it.
  • You should configure DNS appropriately for a hostname before the site goes live. This is because if DNS is not configured appropriately for a hostname well before the site goes live, we will not have an SSL certificate available at go-live time, and this will cause immediate downtime for a hostname.
  • You should review the rate limitations in place from our SSL provider; this means you will have to take some care with how you add hostnames to sites so that you do not violate them. These rate limits include activities OFF of our systems as well, so it is possible that a domain or hostname can get locked out from being able to request new certificates mentioning it for a week, and this is not a limitation over which we have any influence or ability to “reset”; only time can do that. We’ll be happy to advise in more detail if you like; just ask!
  • Consider how many hostnames for customers you are likely to need. Any Netlify site can serve EITHER any number of hostnames matching the *.somedomain.com pattern OR a maximum of about 90 specific hostnames on a single configured site. If you plan to have hundreds of customers each using their own vanity domain you will need to use multiple sites, to each hold a separate list of names. This will be necessary since one list of all names would be too long to fit into a single-site “bucket” - even if you only have one codebase for all of your customers.
  • Please check in with our Support or Sales teams if you resell Netlify’s web hosting - this means you charge your customers for web hosting using our service. We need to ensure your usage is in compliance with our terms or service, which says effectively that you must be a Pro or higher customer if you resell our service.
  • Lastly, as a reminder, we will not be able to provide tech support to your customers for this confoguration. We will provide support only to you, and you will have to support your customers in their configuration, should they need help.

Recommended Method

The smoothest way to handle one-hostname-per-customer is to create hostnames that you manage. Instead of a name like yourbusiness.yourcustomer.com, use yourcustomer.yourowndomain.com. This allows you to set up a single site and SSL certificate to cover *.yourowndomain.com using our wildcard domain feature, and this lets you add additional customers with no additional config. Please note that this wildcard domain feature is available only for Pro and higher customers.

Some of our larger customers have scaled this workflow to millions of customers hosted on a single site, each using vanity domains in a pattern like the ones above. In the case that you need different code deployed to each site, you can ensure that our Support and Forums team will be able to directly help advise with DNS configuration by using the naming pattern of customer1.yourowndomain.com , customer2.yourowndomain.com , and so forth.

The major upside to this configuration is that you can pre-configure an SSL certificate for *.yourowndomain.com or *.customers.yourowndomain.com meaning that as soon as DNS is setup and your content is deployed, Netlify is ready to serve it. Further, much of the complication in hosting many disparate hostnames is around needing to configure DNS for many hostnames, and allow us time to provision SSL for many hostnames - which difficulty evaporates when you can configure a single DNS record and SSL certificate for all of your customers.

Another Option

However, most folks usually request a different way to do this, and ultimately create customer domains such as yourservice.yourcustomer.com. While we have several customers using this pattern successfully, one thing in common is that we’ve had to teach all of them how to diagnose DNS misconfiguration with their customers. There are a dozen or so potential failure modes, some more obvious than others, which you’ll need to become familiar with and assist your customers in avoiding. An example of these failure modes are mixed records pointing to Netlify and also not to Netlify, or CAA records that block our SSL provider from issuing certificates. This is also likely to lead to delays in the site being available for service as DNS must be configured to point to us, and the changes must be propagated, and finally, a site on our service must be configured to serve that hostname, before we’ll serve traffic correctly for that hostname.

Implementation Details

There are some nice workflows that can go with either pattern, such as adding hostnames to a site via our API, and configuring automating configuration for enough sites such that each serves a small list of hostnames, and we’ll be happy to speak to those in a thread you start from this Support Guide!