Domain Mappings

Domain Mappings

 

Introduction

Catalyst Domain Mappings enables you to map your own domain address with the production URL of the Catalyst application. After you map your domain with a specific Catalyst application, you can provide the URL of your own domain to the end-users of your application. They will then be able to access your Catalyst application's client end from your domain's address directly, instead of accessing the default production URL of the application.

Catalyst also enables security for all the domains that you map with your applications, by providing Group SSL certificates for them at no cost. You can create domain mappings and manage all of your mapped domains in an integrated space, using the Catalyst console.

Note: Domain Mappings is only available in the Production environment. You can map domains and configure the mappings only after you deploy your application to production and work from the production environment.

Points to remember about Catalyst Domain Mappings:

  • You must already have the domain hosted live, to map it with the Catalyst application using Domain Mappings.
  • The default production URL provided by Catalyst will still be active after you map it with an external domain. You can access the client endpoint with the default development or production URLs at all times.
  • You can associate only one unique domain with one Catalyst application. You will not be able to add the same domain address for a different Catalyst application.
  • You can map multiple domains with a single Catalyst application. You can configure mappings for up to 5 domains in each application.
  • You can disable or delete a mapping any time you need, and use only the default URL of the application.

To learn about the actions you can perform in Domain Mappings in the production environment, refer to the Environments help page.

 

Architecture

A domain mapping works by associating the CNAME entry of your domain with the Catalyst hosting site in your domain's DNS configuration. You can learn about the steps to do it in detail in the Implementation section.

You must add two CNAME records for your domain to link it with Catalyst in your domain's DNS configuration. You must use the unique hash key value generated for the mapping by Catalyst in the second CNAME record. This will verify your ownership of the domain and create a unique mapping on both ends.

After verifying your ownership of the domain, Catalyst will create a unique key-value pair for the DNS entry, which will associate that particular domain with the specific Catalyst application. It will maintain a reverse mapping of the domain and the application endpoint. This ensures that the domain is uniquely associated with only one Catalyst application until the mapping is deleted.

 

Benefits

  1. Easy and Quick Mapping Process

    The domain mapping process can be completed easily in three steps from the Catalyst console. You will only need to make minor changes in your domain's DNS configuration to enable mapping with Catalyst. You can exit the mapping process at any time and continue from right where you left off.
  2. Exposing your domain URL to end users

    The ability to provide a URL of your organization's domain to your Catalyst application users, instead of only using Catalyst's default URL, enhances the brand value and professionalism of your organization. It helps you with marketing and creating a good reputation for your brand.
  3. Enterprise-level security for your domain

    Zoho's mandatory Group SSL certificate ensures safety for your domain and enables you to distribute a secure endpoint of your application to your customers or application users. You don't need to spend additional money and procure an SSL certificate on your own for your domain. Catalyst also auto-renews the SSL certificate each time before it expires. This frees you from the responsibility of managing the security of your domain entirely, and saves you from the effort involved in it.
  4. Accessing your application with a custom URL

    You can map up to 5 domains for each Catalyst application, allowing you to expose different URLs to different groups of end users based on your business logic. You can also continue using the default development URL when you're working in the development environment in your console, or the default production URL for testing and other purposes.
 

Implementation

The Implementation section explains the process of configuring the DNS settings of your domain and mapping it with your Catalyst application in detail.

Add a Domain Mapping

The steps involved in mapping your domain with Catalyst are:

1. Create a CNAME record in your domain's DNS configuration and map the entry with Catalyst

As mentioned in the introduction, the domain that you want to map with a Catalyst application must already be hosted live in your domain provider's hosting site. Some commonly used domain hosting services include Bluehost, GoDaddy, Google Domains, Hostgator, Hostinger, DreamHost, and more.

When you host your domain, your domain provider will give you access to an administrative console where you can configure and manage your domain. You must create a CNAME record for your domain and associate the entry with Catalyst using your provider's administrative console.

The consoles may vary depending on the domain provider, but you must follow these basic steps to create and map a CNAME record with Catalyst:

  1. Log in to your domain provider's administrative console.
  2. Go to the DNS Configuration/DNS Settings/Manage DNS section of your hosted domain.
  3. Create a CNAME record for your domain by adding the following values:
    • Your subdomain's value as the Host Name/Alias/CNAME.

      For example, if your domain address is "portal.zylker.com", you must add "portal" as the Host Name/Alias/CNAME value.

      If the domain is "www.zylker.com", you can add "www" as the Host Name/Alias/CNAME value.
       
      Note: Ensure that you specify the subdomain, since Catalyst currently does not support base domains to be mapped directly with an application URL.
    • "catalyst.cs.zohohost.com" as the Destination/Points To value.
       
      Note: We will add another CNAME record later and use the hash key generated by Catalyst in it, after you add the domain in Catalyst.
  4. Save the changes.

The changes might take some time to be reflected on the DNS server, based on the DNS register and the domain provider that you are using.

2. Add the domain in the Catalyst console for your project

After the changes are reflected in your DNS configuration, you can begin with adding a domain mapping for your Catalyst application in the following way:

  1. Switch to the production environment, then navigate to Domain Mappings under Host and Manage in your Catalyst console for the specific Catalyst project.
  2. Click Add Mapping.
  3. Enter the domain URL in the pop-up window.
    Note: Ensure that the domain URL you add is hosted live. If you attempt to add an inactive or an invalid domain in Catalyst, the console will display a "Host not found" error. Likewise, if the CNAME entry has not been created and mapped to catalyst.cs.zohohost.com, the console will display a "CNAME not mapped correctly" error when you attempt to add it.
  4. Click Next.

Catalyst will now generate a unique hash key value for the specific mapping as mentioned earlier. This value, along with the URL of the Catalyst hosting site, will be displayed in the next stage of the pop-up window.

3. Create another CNAME record and add the hash key value generated by Catalyst

You must now create another CNAME record in your DNS configuration to add the hash key value generated by Catalyst in it:

  1. Open your domain provider's administrative console again.
  2. Go to the DNS Configuration/DNS Settings/Manage DNS section of your hosted domain.
  3. Create a new CNAME record for your domain and add the following values:
    • hash_key.subdomain as Host Name/Alias/CNAME

      For example, if the hash key generated by Catalyst is "c12to00001x11pl1234h9e33w44h6789", and the subdomain is "portal", you must enter the Host Name as "c12to00001x11pl1234h9e33w44h6789.portal".
       
      Note: Ensure that you specify the subdomain, since Catalyst currently does not support base domains to be mapped directly with an application URL.
    • "catalyst.cs.zohohost.com" as the Destination/Points To value.
  4. Save the changes.

The changes might take some time to be reflected on the DNS server. Once the changes are reflected, this will verify your ownership of the domain in Catalyst.

You can then click Verify in the pop-up window in Domain Mappings to proceed to the next step.

4. Request a Group SSL certificate from Catalyst and install it through Zoho

You must now request a Group SSL certificate from Catalyst for your domain and have it installed through Zoho. Catalyst provides this security certificate for your domain free of charge. This is a mandatory procedure, as your Catalyst application will not be accessible at that domain without an SSL certificate from Zoho. Even if you already have an SSL certificate enabled for your domain, you must use only Zoho's SSL certificate for the domain to be mapped successfully.

To obtain a Group SSL certificate, you must write to Catalyst support at support@zohocatalyst.com with the details of your domain address. Catalyst will provide the certificate and activate it within 48 hours. You can then install it for your domain. Catalyst will auto-renew the SSL certificate each time automatically before it expires.

5. Apply the configurations and enable the domain mapping for your application

After you install the Group SSL certificate for your domain, you can apply the configurations for the domain mapping in the pop-up window by clicking Apply.

If all the steps have been processed successfully, the domain mapping will be live. All the domains you configure for your Catalyst application will be listed in the Domain Mappings page.

You can close the pop-up window at any time during the process and the configurations you made so far will be saved automatically. Verification Status and Domain Status will display the current status of your domain.

If you close the pop-up window before requesting the SSL certificate, you can click the Apply Domain button under Domain Status after installing the certificate.


 

Disable a Domain Mapping

You can choose to disable a domain mapping temporarily or for a limited period of time. This will make your Catalyst application available only at the default URL endpoint.

The unique mapping associated with the particular application will still be available in Catalyst even when it is disabled. Therefore, you will still not be able to associate the domain with a different Catalyst application when it is disabled. This also allows you to instantly re-enable the mapping any time you require, without needing to configure it all over again.

To disable a domain mapping for your Catalyst application, click the disable icon for the domain.

Note: You can only disable your domain mappings from the production environment.

The mapping will then be disabled. You can re-enable it by clicking the Apply Domain button under Domain Status. This will change the status to "Live" again.


 

Delete a Domain Mapping

You can delete a domain mapping from Catalyst and permanently disassociate the domain from that particular Catalyst application. This will delete the records that Catalyst maintains of the unique association, and allow you to map that domain with a different Catalyst application if needed.

To delete a domain mapping of your Catalyst application:

  1. Click the delete icon for the domain in the Domain Mappings page.
    Note: You can only delete your domain mappings from the production environment.
  2. Click Yes, Proceed in the confirmation pop-up window.

You will now have to re-configure the mapping to associate the domain with the application again.

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocatalyst.com