Custom Domain

Custom domains are available on every ReadMe plan, including the free Starter plan. No paid upgrade is required.

Hosting docs on your company domain is an important part of making your docs polished and professional. You can set up a custom domain from Settings > Custom Domain.

For most configurations, you’ll need to set up a CNAME record for your desired subdomain pointing to the target subdomain-hash.readmessl.com. Refer to your DNS hosting provider’s documentation for information on how to add a CNAME in your domain's settings. For example, if your DNS is hosted by GoDaddy, then refer to its "Add a CNAME Record" article.

Hostname validation and proxies

Typically, hostname validation completes immediately and your custom domain is ready to use within minutes. If your domain sits behind a reverse proxy (NGINX, Fastly, Cloudflare CDN), validation will fail in most cases.

The best practice in the case of reverse proxies is to first point the domain at the provided CNAME value so that ReadMe and our CDN provider may validate ownership. Once that process has completed, and the domain is hosted live, you can then attempt to move ReadMe behind your reverse proxy. If this is not possible, and/or if DNS validation is required for certificate renewal (HTTP passthrough to /.well-know/* isn't possible), Enterprise customers may contact ReadMe Support for special DNS records to manually validate ownership and certificate renewal at our CDN.

Apex Domains vs. Subdomains

You can set the base URL for your ReadMe project to a subdomain (e.g., docs.example.com) or an apex domain (e.g., example.com), but not to a path (e.g., example.com/docs).

If you want to use an apex domain as your custom domain, your DNS host must support alias records for the top-level domain. The top level domain will need to be configured as an alias pointing to the target listed on this configuration page. Additionally, you will need to prove domain ownership at ReadMe via addition of a TXT record where the answer matches the ReadMe-provided CNAME value:

TXT name: _readme.subdomain.example.com

TXT value: subdomain-hash.readmessl.com

Please refer to your DNS hosting provider's documentation for instructions on how to set up an alias.

Typically if the domain is just an Apex domain and not also behind a reverse proxy, the above should be sufficient, however if the SSL certificate isn't building, please contact ReadMe Support and we can assist with manually configuring ownership and certificate renewal at our CDN.

SSL

Upon saving your Custom Domain in ReadMe, if you’ve correctly configured a DNS record in your registrar, we will attempt to generate an SSL certificate on your behalf! ReadMe uses Cloudflare to provision and manage the certificates for custom domains.

Using NGINX as a Custom Proxy

If you have an existing proxy in place for your domain and you would prefer to forward traffic to the target instead of creating a traditional DNS record, there are a couple steps you'll need to complete for proper configuration.

Creating an SSL Certificate for Your Domain

Before making full use of your proxy with ReadMe, you will need to generate a certificate through our system traditionally. This means you will need to complete the above steps (Custom Hostname, SSL). Once your certificate has been created, you can change your DNS record to point to your proxy location and proceed.

Configuring NGINX Routing

Cloudflare relies on Server Name Indication (SNI) to authorize use of its proxy and certificates. Without passing the correct information, you may receive a 403 - Forbidden error on navigating to your domain. Depending on your version, NGINX supports SNI. You will, however, need to explicitly declare two new variables in your configuration: proxy_ssl_server_name and proxy_ssl_name. In tandem, these act as an SNI declaration.

Here's a configuration you can use for NGINX using these settings:

http {
  server {
    listen 443 ssl;
    server_name example.com;

    location / {
      proxy_pass https://ssl.readmessl.com;
      proxy_ssl_server_name on;
      proxy_ssl_name example.com;
      proxy_set_header Host example.com;
    }
  }
}