Common Errors

Cloudflare SSL

In most cases, you don't need to setup Cloudflare in front of your GitBook project because we already serve all content over our own CDN. But doing so might still be useful for an advanced usage, such as setting up custom redirects for your content.

If your domain Crypto > SSL configuration is set to a lower value than Full SSL (strict) on Cloudflare, you are already be good to go. However, as a content hosting company, we enforce our users to adopt the highest security standards by setting this option to its highest level.

Cloudflare Full (strict) SSL mode

Here are the details to setup your custom domain with the Full SSL (strict) configuration, for both a simple or advanced usage.

Simple usage

If your domain is managed by Cloudflare but your project doesn't require any special setup, you can simply disable Cloudflare proxying (the orange icon) for your domain.

Exemple of a domain configured without Cloudflare proxying

This option is the simplest since it only affects this specific domain. Requests to your docs will reach our CDN directly, which already enforces connections over HTTPS.

Advanced usage

With Cloudflare proxying enabled and your SSL settings set to Full SSL (strict) , you might see an SSL error page when accessing your GitBook space. It simply means that, given the current configuration of your domain, our CDN was not able to provide a certificate for your domain name to communicate with Cloudflare over HTTPS.

It is now possible for us to issue a valid cert for your domain, but it requires three steps.

Disabling the global "Always Use HTTPS" option

Turn the global Crypto > Always Use HTTPS option off. In order to provide your domain with a certificate issued by LetsEncrypt, a subset of the routes of your domain must remain accessible through the HTTP protocol. Don't worry, you can still enforce HTTPS for your all your other domains using a Page Rule, as described below.

"Always Use HTTPS" option should be turned off

Allow LetsEncrypt using a Page Rule

Add a Page Rule on your GitBook custom domain to disable SSL on the following routes: /.well-known/acme-challenge/*. This will allow LetsEncrypt to perform the necessary checks to deliver a valid certificate for this domain. If you plan on enforcing HTTPS for all your other routes (see the next section), this Page Rule must be placed before the one that enforces HTTPS.

Turn SSL off for your GitBook custom domain

Enforce HTTPS for your other domains routes using a Page Rule

Though this step is optional, we highly encourage you to do it to maintain the highest level of security on your domain name.

The following Page Rule allows you to enforce HTTPS for all other routes of your domain name:

Enforce HTTPS on all other routes

CAA DNS Record

CAA allows you to control who can issue new SSL certs for your domain.

We leverage LetsEncrypt to issue new certs for custom domains. So if you have a CAA record, you need to make sure it allows LetsEncrypt.

You can fix this by simply adding a new CAA record containing:

0 issue "letsencrypt.org"

Bad Example

0 issue "comodo.com"

Good Examples

0 issue "letsencrypt.org"

or

0 issue "comodoca.com"
0 issue "letsencrypt.org"