How to use your own domain

You will need to have your webmaster create a CNAME entry on your DNS that points your private domain to the KnowledgeOwl subdomain you use in KB settings > Domain.

Example: help.mycompany.com CNAME record pointing to mycompany.knowledgeowl.com

Once your webmaster has created a CNAME record to handle the relationship between your private domain and your KnowledgeOwl subdomain, you can add your private domain:

1. Go to KB settings > Domain.
2. Select Add private domain under Private domain.
   
   Select the Add private domain link in Private domain
   
   The Private domain setup modal opens.
3. Enter the URL you'd like to use as the Private domain name. You can save at this point, but you'll also need to add an SSL certificate.
   
   Enter your private domain in the Private domain name field
   

If your private domain uses https:// (most do, and it's a security best practice), you'll need to set up an SSL certificate. For your convenience, we have an integration with Let's Encrypt to set up an autorenewing certificate at no cost to you.

1. Go to KB settings > Domain.
2. Select the wrench icon next to your private domain (or just continue from adding it in the previous steps!)
   
   Select the wrench icon next to your Private domain.
   
   
   The Private domain setup modal opens.
3. Select Request Let's Encrypt SSL Certificate to set up an autorenewing certificate through Let's Encrypt.
   Click the Request Let's Encrypt SSL Certificate button
4. If your CNAME record is properly formatted and has synced, a success message displays.
   
   Error setting up SSL certificate
   If you get an error message, select the matching error below to jump to more detailed troubleshooting instructions:

   • SSL cert troubleshooting: CNAME record has not fully synced
   • SSL cert troubleshooting: CAA conflict
5. Be sure to Save your changes.

The certificate should appear on your knowledge base within the next 10 minutes. Most browsers let you select the security icon to next to the URL to view the certificate. If this certificate has been applied, you'll see details for a Let's Encrypt Authority X3 certificate, similar to this:

Sample Let's Encrypt certificate

Once the cert is live, follow the next set of instructions to Make all requests use your new private domain.

When your private domain is set up and your SSL cert is working correctly, try navigating to your private domain and confirm your knowledge base is loading.

Once you've confirmed that, we recommend making two additional changes, both in KB settings > Domain:

1. Check the box next to Use the private domain for application links or actions that open your knowledge base, e.g. View KB. This setting guarantees that any time an author uses View knowledge base, View Article, or View Category, they're taken to your private domain, not your KnowledgeOwl subdomain.
2. Check the box next to 301 redirect all sub-domain requests to the private domain. This setting guarantees that if anyone does try to open a page using the KnowledgeOwl subdomain, they'll be redirected to the private domain.

   Public knowledge base SEO recommendation
   This setting is especially important if you have any publicly-available content. It guarantees that search engines only index your content under the private domain, not the KnowledgeOwl subdomain.

3. Be sure to Save your changes!

If you've selected to use reCAPTCHA as your spam protection and set up certain features in specific ways, you may also need to add reCAPTCHA once you've added a private domain.

If you do, you'll see a warning in the KB settings > Domain page after you've saved your private domain settings:

Sample warning in Domain Settings 

You can add the reCAPTCHA Key and Secret further in the Security and access > Security settings.

If you're using honeypot spam protection, you won't need to do anything extra.

If you're using reCAPTCHA spam protection with a KnowledgeOwl subdomain (such as my-amazing-kb.knowledgeowl.com), you don't need to configure your own reCAPTCHA.

If you're using reCAPTCHA spam protection and you've customized your knowledge base to use your own private domain, such as www.mykb.mycompany.com, you'll need to add your own reCAPTCHA to your site if you have any of these options enabled:

• KB settings > Comments: The Only allow logged in readers and authors to leave comments box is unchecked (e.g. you allow unrestricted commenters)
• KB settings > Subscriptions: The Enable public subscriptions box is checked (e.g. you allow public subscriptions)
• Customize > Contact form: The Use spam protection on ticket submissions box is checked
  • If you're using this setting and also using Contextual Help Widget (2.0), you'll also need to add a V3 reCAPTCHA to add reCAPTCHA to the Contact tab on the Widget.
  • If you're using this setting and don't have reCAPTCHA enabled, your contact form will display an invalid domain error to your end-readers.

What is reCAPTCHA?

reCAPTCHA is a free service from Google that helps prevent spam activity in your knowledge base.

It's designed to verify that someone signing up for a subscription is a real person and not a bot. A "CAPTCHA" is a simple test--usually a task that is very easy for a human to perform, but hard for bots and other malicious software to figure out. There are two versions of reCAPTCHA:

• v2: Verify requests with a challenge. Example: checking a box next to "I am not a robot."
• v3: Verify requests with a score. Example: click on all the images that have cars in them.

KnowledgeOwl currently supports specific versions in specific places:

• v2: Supported in the full knowledge base; not supported in Contextual Help Widget (2.0). For these reCAPTCHAs, configurations with "I am not a robot" reCAPTCHAs.
• v3: Supported in Contextual Help Widget (2.0); not supported in the full knowledge base.

Only v2 reCAPTCHAs will work properly in your main knowledge base. We've tested our configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base!

Creating a new reCAPTCHA

To create a new reCAPTCHA, you'll need a Google account.

1. Go to https://www.google.com/recaptcha/admin
2. If you've never generated a reCAPTCHA before, this should take you directly into the page to create one. If you've generated a reCAPTCHA before, you'll need to click the + in the upper right to Create a new reCAPTCHA.
3. Pick a label for your reCAPTCHA. You might use the name of your knowledge base or the URL for it.
4. Select the reCAPTCHA type:
   • For use in your overall knowledge base, use reCAPTCHA v2. The "I'm not a robot" checkboxes work well.
   • For use in Contextual Help Widget (2.0) Contact Form, use reCAPTCHA v3. See Protect Widget 2.0 Contact Form with reCAPTCHA for more information.
5. For domain, use the URL of your KnowledgeOwl knowledge base.
6. Your Gmail account will automatically be added as an Owner. You can add additional email addresses. If you'd like us to be able to help troubleshoot issues with your reCAPTCHA, add support@knowledgeowl.com as an owner.
7. You'll need to check the box next to Accept the reCAPTCHA Terms of Service.
8. You can choose to receive or opt out of alerts to owners. These alerts will notify you if Google detects problems with your site, such as misconfigurations affecting the reCAPTCHA or increases in suspicious traffic. We recommended receiving the alerts.

   So a completed v2 reCAPTCHA might look something like this:

9. Once you've entered all your selections, click Submit.
10. This will take you to a confirmation screen that will provide you with the Site Key and the Secret Key for your reCAPTCHA. You'll need these to add them to your knowledge base!

Add your reCAPTCHA to your knowledge base

With your reCAPTCHA generated, you can add the site key and secret key to your knowledge base. To do so:

1. Go to Security and access > Spam protection.
2. In Spam protection settings, copy and paste your reCAPTCHA site key and secret key from Google into the appropriate fields here.
   Note the different sections for reCAPTCHA Key V2 and reCAPTCHA Key V3. Be sure you're using the right ones!
3. When you're done making changes, click Save.

Error message text:

The CNAME record for [your private domain] has not fully synced yet.

Please ensure you have added a CNAME DNS record for this domain.

You'll see this error message if:

• You've entered a private domain but your webmaster hasn't created a CNAME record to map the domain to your KnowledgeOwl subdomain.
• Your CNAME record was just created and hasn't synced yet.
• Your CNAME record was improperly formatted.

If you see this message, you may need to create or update your CNAME record or just wait a few more minutes for it to sync.

You may see a warning about a CAA policy not allowing certificates to be issued from Let's Encrypt. It will read something like:

The CAA policy for {yourwebsite.com} does not allow certificates to be issued from Let's Encrypt.

Please refer to our documentation to resolve.

Certificate Authority Authorization (CAA) records and policies determine which authorities are allowed to issue certificates for a given domain. If you see this warning, it means that your domain has a CAA which does not include Let's Encrypt as a valid authority.

To fix this error, contact your IT department/network admin and ask them to add letsencrypt.org to the current CAA policy or record.

Once they've added Let's Encrypt as an authorized authority, come back and request the SSL cert again.

If your company rebrands or changes up their website, you may need to change the private domain associated with your knowledge base. When you change your knowledge base's private domain, this will break links to your previous private domain.

To avoid breaking any existing bookmarks or links, you or your webmaster can set up a redirect in your domain registrar account to forward your previous private domain to your new private domain. That way, anyone visiting a link using the old domain will be forwarded to the right place.

Here are the basic steps for changing your private domain:

1. Have your webmaster create a CNAME record in the DNS settings for your new domain that points the new domain to your KnowledgeOwl subdomain shown in KB settings > Domain.
   Example: help.mycompany.com CNAME record pointing to mycompany.knowledgeowl.com
2. Have your webmaster set up a redirect from your previous private domain to your new private domain.
   Example: redirect helpcenter.mycompany.com (your old private domain) to help.mycompany.com (your new private domain)
3. In the DNS settings for your previous private domain, have your webmaster remove the CNAME record that was pointing that domain to your KnowledgeOwl subdomain.
4. In your KnowledgeOwl account, navigate to KB settings > Domain.
5. Select the wrench icon next to your current private domain.
   
   Select the wrench icon next to your private domain
   
   
   The Private domain setup modal opens.
6. In the Private domain name field, replace the old private domain with your new private domain. 
7. Select Request Let's Encrypt SSL Certificate to set up an autorenewing certificate through Let's Encrypt.
8. If your new CNAME record is properly formatted and has synced, you'll see a success message.
9. Be sure to Save your changes.

Your knowledge base should now be using your new private domain and your SSL certificate will appear within the next 10 minutes. Any links to your old knowledge base's private domain will redirect to the new domain.