Setting Custom Domain & SSL
Custom Domain
If you would prefer to have your project be behind a domain of your choosing, you can set up a Custom Domain
with ReadMe! You can configure this under Documentation > Configuration > Custom Domain.
Custom domains and subdomains vs. paths and folders
Projects can be set to a custom domain (
hoot.at
) or subdomain (docs.hoot.at
), but cannot be set to a path or folder (hoot.at/docs
).
For most configurations, you'll need to set up a CNAME record for your desired subdomain pointing to ssl.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.
If you want to use a top-level domain as your custom domain, i.e. example.com
, 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 ssl.readmessl.com
. Refer to your DNS hosting provider's documentation for instructions on how to set up an alias.
Setting a Custom Domain will automatically force all users to https.
SSL
Upon saving your Custom Domain
in ReadMe, if youβve correctly configured a DNS record in your registrar pointing to ssl.readmessl.com
, we will attempt to generate an SSL certification on your behalf! ReadMe uses Cloudflare to provision and manage the certificates for custom domains.
Cloudflare Customers
Cloudflare does not currently support "Orange-to-Orange" network traffic (multiple proxies managed by Cloudflare). If you are currently using a Cloudflare proxy, you must disable the proxy in your settings.
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 ssl.readmessl.com
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.
Certificate Status
You can check the status of your certificate by navigating directly to your custom domain. If you can access your ReadMe's documentation via your custom domain, and there is a lock in the URL bar, you're good to go!
In the future, we plan on adding direct verification via the
Custom Domain
page!
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;
}
}
}
Updated 5 months ago