Setting Up a Custom Domain

Every HelpDocs customer gets a subdomain that looks like this: <your-subdomain>.helpdocs.io. Subdomains work great for most customers.

But if you want to take your customer experience from good to amazing, you'll want to set up a custom domain. Something like support.yourapp.com.

Setting up a custom domain is super simple. But if DNS and CNAMEs aren't your thing, forward this article to your developers.

Setting up your custom domain

1

Set up a CNAME record

Log into your DNS provider. This could be Route 53, GoDaddy, or whoever manages your domain. Create a new CNAME record for your chosen subdomain.

Point it to domains.helpdocs.io. Set the TTL as low as possible.

If you're using Cloudflare for DNS, your record should be grey-clouded with the proxy turned off. Orange clouding can cause issues.

Your CNAME should point to domains.helpdocs.io exactly as written. Don't substitute your HelpDocs subdomain.

2

Tell us what your domain is

Now you need to tell HelpDocs about your custom domain.

1. Head to Settings > General in your account
2. Type your custom domain into the field
3. Hit Save Changes

3

Wait for DNS to propagate

DNS providers aren't always as fast as we'd like 🙁

You might need to wait up to 48 hours for changes to take effect. Don't worry though. You can still access your Knowledge Base at your original subdomain during this time. Once propagation completes, visiting your custom domain should display your Knowledge Base.

Add SSL to your custom domain 🔒

All HelpDocs plans come with free SSL certificates. There's nothing extra to pay and it only takes one click. Here's how to add SSL to your custom domain:

1. Make sure your custom domain works without SSL first
2. Head to Settings > General
3. Next to Custom Domain, click Request SSL
4. Your certificate should be ready in a few seconds
   If your certificate doesn't appear after several minutes, contact support and we'll help you debug 🐛
5. Once SSL is working, the Request SSL button will disappear. You'll see https:// in the domain field prefix

Troubleshooting common issues

Running into problems? Here are the most common issues and how to fix them:

Moving a domain to HelpDocs with zero downtime

You can move your existing docs to HelpDocs without any downtime. Here's how:

1. Enter your custom domain in HelpDocs Settings > General and hit Save
2. Update your domain's CNAME to point to domains.helpdocs.io
3. Wait for your custom domain to show HelpDocs content
4. Optional: Generate an SSL certificate in Settings > General by clicking Request SSL

Custom domain via CloudFront

Using Amazon CloudFront with your custom domain? By default, CloudFront doesn't forward your visitors' User-Agent to HelpDocs. It replaces it with "Amazon CloudFront" instead.

This may break some analytics functionality like:

• Pageview analytics
• Browser and device data
• Language detection
• AI crawler identification
• Bot filtering

Fix: forward viewer headers with an Origin Request Policy

1. Head to your CloudFront distribution in AWS Console
2. Head to Behaviors and edit the behavior pointing to HelpDocs
   1. Set Origin request policy to:
      Managed-AllViewer (recommended): forwards everything and restores full functionality
      Managed-AllViewerAndCloudFrontHeaders-2022-06: same as above plus CloudFront's geo/device headers

3. Save the changes. CloudFront will update in 1-5 minutes