Each knowledge base has its own unique KnowledgeOwl subdomain, like ours is "support.knowledgeowl.com". Your subdomain can be customized under Settings > Basic, in the Domain Settings section.
You can also set up a private domain (your own custom URL with no reference to KnowledgeOwl) and point that to your KnowledgeOwl subdomain. You or your webmaster will need to add a CNAME record for your subdomain. Once created, the private domain may take up to 24 hours to be fully synced.
If your private domain uses https:, you can use our integration with Let's Encrypt to provide an automatically renewed SSL cert for your knowledge base, too!
Here's the overall process:
- Have your webmaster set up a CNAME record that points your private domain (such as help.mycompany.com) to your KnowledgeOwl subdomain shown on Settings > Basic (such as mycompany.knowledgeowl.com).
- In Settings > Basic, add the private domain.
- Once the private domain has synced, generate a Let's Encrypt SSL certificate. The domain can take up to 24 hours to sync, but usually it completes in a few minutes.
- If you're using features that leverage reCAPTCHA, add a reCAPTCHA key.
See below for more detailed information on each step and how to troubleshoot errors you might run into.
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:
- Go to Settings > Basic.
- Click the Add private domain link next to Private Domain
- 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.
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.
- Go to Settings > Basic.
- Click the wrench icon next to your private domain (or just continue from adding it in the previous steps!)
- This will open a Private Domain Setup popup.
- Click the Request Let's Encrypt SSL Certificate button to set up an autorenewing certificate through Let's Encrypt.
- If your CNAME record is properly formatted and has synced, you should see this success message:If you get an error message, click here to troubleshoot:
- 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:
Depending on the settings you've selected, 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:
You can add the reCAPTCHA Key and Secret further below in the Domain Settings section.
If you are using a KnowledgeOwl subdomain (such as my-amazing-kb.knowledgeowl.com), you don't need to configure your own reCAPTCHA.
However, if you have 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 users 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)
- Knowledge Base > Contact Form: The "Require ReCaptcha "I'm not a robot" validation to submit a ticket" box is checked
What is reCAPTCHA?
reCAPTCHA is a free service from Google 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.
Only v2 reCAPTCHAs will work properly in KnowledgeOwl. 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.
- Go to https://www.google.com/recaptcha/admin
- 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.
- Pick a label for your reCAPTCHA. You might use the name of your knowledge base or the URL for it.
- Select the v2 reCAPTCHA type. The "I'm not a robot" checkboxes work well.
- For domain, use the URL of your KnowledgeOwl knowledge base.
- 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 email@example.com as an owner.
- You'll need to check the box next to Accept the reCAPTCHA Terms of Service.
- 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 reCAPTCHA might look something like this:
- Once you've entered all your selections, click Submit.
- 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:
- Go to Settings > Basic.
- In Domain Settings, copy and paste your reCAPTCHA site key and secret key from Google into the fields here:
- 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:
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.