Custom Domains

By default, Launch generates a unique URL of the form example.contentstackapps.com for every environment. Each environment is assigned to a unique subdomain at contentstackapps.com.

To make your site easy to access and remember, you need a human-friendly domain name. Contentstack Launch allows you to add custom domains to your environment. Follow the steps below to configure your custom domain.

Note Custom subdomains must not exceed 255 characters in total length, as per the RFC 1035 specification. For example, www.example.com, www.example.org, subdomain.example.in

Tip After setting up a custom domain, the default *.contentstackapps.com domain remains accessible. Launch automatically prevents this default domain from appearing in search results by applying an X-Robots-Tag: noindex header; no action needed on your part. For additional protection options, refer to the Blocking Default Launch Domains From Google Search guide.

• How to add a custom subdomain or apex domain to an environment.

• How to configure redirection options for apex domains.

• How to verify domain ownership and provision an SSL certificate.

• How to read domain and certificate statuses, and how to delete a custom domain.

Contentstack Launch lets you add custom apex domains and subdomains to your environments for more flexible domain management.

Follow the steps below to add a custom domain to an existing domain. In this example, we will configure a subdomain for example.com.

1. Click the project card to open your project from the Launch landing page.
2. In the Environments screen, click an existing environment or create a new environment. We will add a custom domain to the Default environment for this tutorial.
3. In the Default environment, click the vertical ellipses under Actions and then click Settings to go to the Settings page.
   Click to enlarge

4. In Environments under Settings, click Domains. 
   Click to enlarge
5. Click the + New Domain button.
   Click to enlarge
6. In the Domain Name field, enter the subdomain name in the following format: <name>.<apex domain>
   For example: www.example.com, domain.example.com
   If you are creating an apex domain instead, enter only the <apex domain>, such as example.com
   After entering the subdomain name, the DNS Details section gets auto-populated as shown below:
   Click to enlarge
   The Value field displays the default subdomain.
   Note

   • If you create an apex domain instead, an A record appears in the DNS section, instead of the CNAME record shown above.
   • When you create an apex domain, No Redirection is selected by default. To enable redirection, learn how to add apex domains with redirects.
7. Click the Create Custom Domain button.
   You can see the newly created domain listed in the Domains page. 
   Click to enlarge

Contentstack Launch supports redirection-only services for apex domains, following industry best practices. Rather than serving traffic directly from the apex domain (e.g., example.com), many top websites redirect users to a subdomain like www.example.com.

This approach offers several key advantages:

• Improved Security: Segregating content delivery and domain management helps reduce the attack surface and enhances overall security.
• Enhanced Flexibility: Easily switch infrastructure or hosting setups without impacting the user-facing subdomain.
• Consistent User Experience: Delivering content via a subdomain ensures better structure, brand consistency, and trust.
• Improved Performance: Subdomains support CNAMEs, enabling CDNs to route traffic across multiple geolocations for faster content delivery.
• Better Cookie Handling: Cookies set on the apex domain apply to all subdomains, which can pose a security risk in multi-tenant systems. Redirecting helps isolate this behavior.
• SEO Benefits: Redirecting to a single subdomain helps avoid duplicate content issues, supporting cleaner SEO practices.

In this setup, Launch ensures that all content is exclusively served from the designated subdomain, providing users with a seamless and efficient hosting solution for their websites.

To configure redirection for an apex domain, choose from the following options when creating the domain:

• No Redirection: This option allows you to add an apex domain without redirecting it to another subdomain or apex domain. Use this when you want the apex domain (e.g., example.com) to serve content directly.
  Click to enlarge
• Add www.apex.com (subdomain) and redirect apex domain to it: This option allows you to add an apex domain (e.g., example.com) and redirect it to a subdomain (e.g., www.example.com). As a result, traffic to the apex domain is redirected to the www subdomain, rather than being served directly from the apex domain.
  Click to enlarge

  Note When you select this option, two domains are created. An apex domain and a www subdomain.

• Custom Redirection: This option allows you to add an apex domain (e.g., example.com) and redirect it to an existing subdomain (e.g., blog.example.com), or another apex domain within the same environment. 
  Click to enlarge

  You can also choose a redirection status code from the following options:

  • 308: Permanent Redirect
  • 307: Temporary Redirect
  • 301: Moved Permanently
  • 302: Found

By default, Launch automatically issues and manages an SSL certificate for every custom domain. If your organization requires a certificate from your own Certificate Authority (CA), you can upload one instead.

This choice appears in the Add Domain (and Edit Domain) modal, under SSL Certificate:

1. Choose one of:

• Automatic (recommended): Launch issues and renew the certificate for you. Continue to Domain Ownership Verification, below.
• Custom certificate: supply your own certificate, private key, and (if needed) intermediate certificates.

1. If you select Custom certificate, three fields appear:

Each field also accepts a click on Upload file to select a .pem, .crt, .cer, .key, or .txt file, its contents loaded into the field, where you can still review or edit them before submitting.

Every field expects standard PEM format — a block starting with a -----BEGIN...----- line and ending with a matching -----END...----- line. The example below is illustrative only (a throwaway test certificate, shortened for readability) — your real files will be longer and provided by your CA, but the shape is the same:

Certificate (PEM), for a domain named abc.example.com:

-----BEGIN CERTIFICATE-----
MIIBwDCCAWagAwIBAgIUDxcdOJ92uYUKPE4ZCD3S5W50KecwCgYIKoZIzj0EAwIw
JjEkMCIGA1UEAwwbTGF1bmNoIFRlc3QgSW50ZXJtZWRpYXRlIENBMCAXDTI2MDgz
...
YmMuZXhhbXBsZS5jb20wHQYDVR0OBBYEFFicWDerfGxx3rTD4EpX31H0ZFe2MB8G
-----END CERTIFICATE-----

Private Key (PEM): the key generated together with that certificate's request:

-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIOUGGqduUUtzQMWKq7SQ1e5fG2pqrxath69mOyZ7xRTvoAoGCCqGSM49
AwEHoUQDQgAEH2HRPPdRQDujYjU9nWfHiHqd0TL3AirHdeMGyAifPnDNt4Aninw5
2jnogi9JFXcKGEbcLxsz/9QAzJu+0KzPhw==
-----END EC PRIVATE KEY-----

Intermediate certificates (PEM): the CA's own chain certificate, not specific to your domain:

-----BEGIN CERTIFICATE-----
MIIBsjCCAVmgAwIBAgIUdP8jXAc7ZtHacIOmZKPrStujmMcwCgYIKoZIzj0EAwIw
JjEkMCIGA1UEAwwbTGF1bmNoIFRlc3QgSW50ZXJtZWRpYXRlIENBMCAXDTI2MDgz
...
XG/6hqxSfKU2D8W1GFdvDEYb8b4CICsxFF0MhQB2qeoYr82PkKLStBAYE0Lx10pN
-----END CERTIFICATE-----

Note If your certificate authority already gave you the full chain, your certificate and its intermediates concatenated into one file, you can paste that whole file into Certificate and leave Intermediate certificates empty; Launch reads the chain from whichever field you use.

Click to enlarge

Click to enlarge

Note Launch checks the certificate before saving it, that it's correctly formatted, that the private key matches it, that the chain is complete and in order, and that it isn't expired. If a check fails, an error notification names the specific reason.

To switch a domain back to Launch-managed certificates later, edit the domain, choose Automatic (recommended), and save.

Note Renaming a domain that uses a custom certificate re-issues its SSL configuration, so you'll need to supply a certificate covering the new name before saving or switch the domain to Automatic first.

Launch does not renew a custom certificate for you. When you add or update one, you will get a notification confirming it and stating its expiry date, and two more reminders as it approaches expiry, at 30 days and again at 14 days before it expires (Cloudflare's fixed thresholds; not adjustable), so you have time to renew with your CA and re-upload. A domain using a custom certificate is also marked in the domains list, so you can tell at a glance which ones you're responsible for renewing.

Domain validation confirms your ownership or control of a domain. This helps prevent unauthorized use and ensures secure traffic routing through your platform. Contentstack Launch uses TXT record validation to verify domain ownership and DCV records to provision SSL certificates. This method is secure, easy to set up, and widely supported.

Use these methods before adding A or CNAME records and routing traffic to Launch, especially for existing live sites migrating to Launch.

After successfully creating an apex or subdomain, you must validate both the hostname and the associated SSL certificate. To do so, perform the following steps:

1. Click the vertical ellipses under Actions for the domain you have added, and then click Edit.
   Click to enlarge
2. In the DNS Details section, perform the following steps to validate:
   • Hostname Validation Record:
     1. Locate the Hostname Validation Record section to view the TXT records required for validation.
     2. Click the copy icon next to the Name and Value fields to copy the TXT record details.
        Click to enlarge
     3. Paste the copied details into your domain provider platform.

     Below are the documentation links to common DNS providers for adding TXT records.

     • Go-Daddy
     • Bluehost
     • Namecheap
   • Certificate Validation Record:
     1. Locate the Certificate Validation Record section.
     2. Click the copy icon next to the Name and Value fields to copy the DCV CNAME record details.
        Click to enlarge
     3. Create a new CNAME record in your domain provider and add these DCV name and values.

     Below are the documentation links to common DNS providers for adding DCV records.

     • Go-Daddy
     • Bluehost
     • Namecheap
3. After adding the records, check your domain status in the Domain Status section.

After both the domain and certificate statuses are active, add an A record or CNAME record under DNS Record section with your DNS provider:

1. In the Edit modal, locate the DNS Record section below the Certificate Validation Record (DCV) section.
2. Copy the provided Name and Value, then paste them into your DNS provider's settings.
   Click to enlarge

Note The TXT record will no longer be visible once your hostname status is active.

• Active: The custom domain has successfully completed validation and is active.
• Pending: The custom domain is awaiting validation.
• Error: The custom domain could not be validated. Review the DNS settings and try again.

  Note Hover over the Pending or Error status to view the error message and error code in a tooltip. Copy the message for further troubleshooting.

Note If your DNS is managed through a Cloudflare zone, an additional Orange-to-Orange (O2O) setup is required. The detailed steps for this configuration are outlined in the Contentstack Go-Live Guide, which can be referred for the implementation guidance.

A domain using a custom certificate also shows a document icon next to its status. Hovering it displays: Custom certificate - renewal is manual, you'll need to re-upload it before it expires.

Launch allows you to delete a custom domain that you no longer require.

Follow the steps below to delete a custom domain:

1. In the Environments screen, go to the environment for which you want to delete the domain.
2. In the selected environment, click the vertical ellipses under Actions, and then click Settings.
3. In the Settings page, click Domains under Environments.
4. In the selected domain, click the vertical ellipses under Actions and then click Delete.
5. A confirmation modal appears. Click Yes, Delete to confirm. 
   Click to enlarge

WarningAfter deleting this domain, remove all related DNS records from your DNS provider to keep your domain secure.