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 Settings > Basic.

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 Settings > Basic.
2. Click the Add private domain link next to Private Domain

   Click the Add Private Domain link on Settings > Basic

3. This will open a Private Domain Setup popup. Enter the URL you'd like to use for your private domain. You can save at this point, but you'll also need to add an SSL certificate.
   Sample private domain

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 Settings > Basic.
2. Click the wrench icon next to your private domain (or just continue from adding it in the previous steps!)
   
   

   
   

3. This will open a Private Domain Setup popup.
   Sample private domain
4. Click the Request Let's Encrypt SSL Certificate button to set up an autorenewing certificate through Let's Encrypt.
   Click the Request Let's Encrypt SSL Certificate button
5. If your CNAME record is properly formatted and has synced, you should see this success message:
   SSL cert confirmation message
   If you get an error message, click here to troubleshoot:

   • SSL cert troubleshooting: CNAME record has not fully synced
   • SSL cert troubleshooting: CAA conflict
6. Click Save.

The certificate should appear on your knowledge base within the next 10 minutes. Most browsers let you you click the security icon 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

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 Settings > Basic in the Domain Settings section, directly underneath your private domain:

1. Check the box next to Enable private domain link in the application. This will ensure that any time one of your authors clicks the View KB button in the top navigation or the View Article/View Category link in the editor, they are taken to the private domain, not your KO subdomain.
2. Check the box next to 301 redirect all sub-domain requests to the private domain. This will ensure that if anyone does have your KO subdomain link, they'll be redirected to the private domain. This setting also ensures that any pages of your knowledge base which are publicly available will only be indexed by Google or other search engines under the private domain, not the KO 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 Domain Settings section after you've saved your private domain settings:

Sample warning in Domain Settings 

You can add the reCAPTCHA Key and Secret further below in the Spam Protection Settings section.

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.

However, 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:

• Settings > Comments: The "Only allow logged in readers and authors to leave comments" box is unchecked (e.g. you allow unrestricted commenters)
• Settings > Subscriptions: The "Enable public subscriptions" box is checked (e.g. you allow public subscriptions)
• Contact Form: The "Use spam protection on ticket submissions" box is checked
  • If you are 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 are 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, and you can see one in action if you try to subscribe to a category in this knowledge base.
• 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 Settings > Basic.
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!
   Add reCAPTCHA keys into the appropriate sections in Spam Protection Settings
3. When you're done making changes, click Save.

If your CNAME record hasn't been created yet, was just created and hasn't synced, or was improperly formatted, you might see this message:

Sample CNAME warning message 

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:

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 it looks like 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 Settings > Basic.
   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 Settings > Basic.
5. Click the wrench icon next to your current private domain.
   Click the wrench icon to edit your current private domain
6. In the Private Domain Name field, replace the old private domain with your new private domain. 
7. Click the Request Let's Encrypt SSL Certificate button to set up an autorenewing certificate through Let's Encrypt.
8. If your new CNAME record is properly formatted and has synced, you should see this success message:
   SSL certificate success message
9. Click Save.

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 private domain will redirect to the new domain.