Let's Encrypt is a free, automated, and non-profit certificate authority.
It will generate a certificate for your domain as long as you can prove that you own it.
During the wizard, RavenDB will give you a free subdomain. This will let you configure the DNS records for this subdomain to point to the IP addresses your server will listen to. The subdomain is owned by RavenDB, and you can manage it through our Customer Portal. Login with your license key, and you can add/remove/update DNS records for your cluster.
The free subdomain is given to you only for the purpose of proving ownership to Let's Encrypt. If you wish to use your own domain, you are welcome to acquire your own certificate and use that instead.
Security consideration and ownership of certificates and domains
The automatic setup is designed to be as convenient and as easy as possible. It takes care of all the details of setting up DNS records, generating certificates, and performing their renewals. Because of these requirements, the ownership of the certificates and DNS records needs to stay within the Hibernating Rhinos company. This gives us the ability to generate valid certificates and modify DNS settings for your registered domains and should be a consideration to keep in mind while reviewing the security of your system.
Hibernating Rhinos will never exploit these abilities and will never perform any modifications to the certificates and DNS records unless explicitly requested by the client.
The purpose of this feature is to make it easy for users to get set up and running with a minimum of fuss. We recommend that for actual production deployments and for the highest level of security and control, you'll use your own certificates and domains, avoiding the need to rely on a third party for such a critical part of your security.
After choosing the Let's Encrypt Secure Setup option, you are required to enter your license key which was sent to the email address you provided. This process will associate your license with the chosen subdomain to ensure that valid certificates can only be generated by a single license holder.
The next step is to name and claim your subdomain.
Configuring The Server Addresses
In the next screen, you will choose the IP address and port that your server will bind to.
If you wish to setup a cluster of servers/nodes (for a more stable, robust, and available database), this is the place to add nodes to the cluster and choose their IP addresses.
For a smooth setup experience, please make sure that the IP address and port are available in each machine. The wizard will validate this and throw an error if they are being used. When using port 443, you need to ensure that it hasn't already been taken by other applications like Skype, IIS, Apache, etc. On Linux, you might need to allow port 443 for non-root processes.
For a list of IPs and ports already in use on your machine, run
netstat -a in the command line.
IP addresses and ports may be changed at a later time by running the setup wizard again which will update the DNS records. Another way is to configure the
settings.json file in each node's server folder. This process requires you to restart your server after configuring.
Example I - On one machine
In the following screenshot, we show an example of constructing a cluster for local development on one machine:
All 3 nodes will run on the local machine:
- Node A (https://a.raven.development.run) will listen to 127.0.0.1 on port 8080.
- Node B (https://b.raven.development.run) will listen to 127.0.0.2 on port 8080.
- Node C (https://c.raven.development.run) will listen to 127.0.0.3 on port 8080.
Each node will run in its own process and have its own data directory and settings.json file. You should have 3 separate RavenDB folders.
Example II - On separate machines
Each node will run on its own machine in a network.
A common scenario for running an internal cluster will be:
- Node A (https://a.raven.development.run) will listen to 10.0.0.84 on port 443.
- Node B (https://b.raven.development.run) will listen to 10.0.0.75 on port 443.
- Node C (https://c.raven.development.run) will listen to 10.0.0.91 on port 443.
You can deploy a cluster that is completely internal to your network and still gain all the benefits of using certificates and SSL with full trust and complete support from all the standard tooling.
A cluster of nodes on separate machines
To enable the nodes to communicate between machines, use the 10.0... IP addresses instead of the 127.0...
Example III - Behind a firewall
A RavenDB server can run behind a firewall (in cloud environments for example).
RavenDB will bind to the private IP address. However, the DNS records must be updated to the external IP address which is reachable from the outside world. Requests made to the external IP address will be forwarded to the private IP address (which RavenDB listens on).
Check the box "Customize external IP and Ports" and supply the external IP address.
Example IV - In a Docker container
In Docker, if you choose to use port mapping with the
-p flag, You need to check the box "Customize external IP and Ports" and supply the external IP address as well as the exposed ports.
So if a container was created using:
sudo docker run -t -p 38889:38888 -p 443:8080 ravendb/ravendb
Then the following configuration should be applied:
Installing The Certificate
When you click next, the wizard will establish a connection with Let's Encrypt to obtain a valid certificate for the entire cluster.
It usually takes this process a couple of minutes to complete. The wizard validates that the DNS records updated successfully and that the server can run with the supplied addresses and certificate and is reachable using the new domain name.
Caching of Let's Encrypt Certificates
In some scenarios you will run the setup wizard again. In that case, if none of the cluster domains changed, the wizard will use the cached certificate and not request a new one from Let's Encrypt.
If the validation fails, you will receive a detailed error. You can go back in the wizard, change settings and try again.
A common error is that DNS records didn't yet update locally.
You may wait a bit and try again. If you do not want to wait, you can configure your network card (just for the setup) to use Google's DNS server (22.214.171.124), to bypass caching of DNS records.
Tip: use dns.google.com to see the DNS record of your domain.
When finished you will receive a Zip file containing all of the cluster configuration files and certificates.
Save this .zip file in your parent folder. It has the security certificate and settings and for each node.
If you are setting up a cluster, you will use this Zip file to set up the other nodes.
Copy the downloaded
<YourDomainName>.Cluster.Settings.zip folder into the Cluster Parent folder to use it later.
If you left the "Automatically register the admin client..." box in the IP setup stage checked (it is checked by default), a client certificate is registered in the OS trusted store during setup. The Chrome and Edge browsers use the OS store, so they will let you choose your certificate right before you are redirected. Firefox users will have to manually import the certificate to the browser via Tools > Options > Advanced > Certificates > View Certificates.
If you unchecked the box, before you continue please register the client certificate in the OS store or import it to the browser.
Install client certificate into browser Run Certificate Import Wizard
A. Extract the downloaded configuration .zip file
<YourDomainName>.Cluster.Settings.zip to the parent folder.
B. Run the
admin.client...pfx file to start the certificate import wizard. In most cases, it is configured to work best by clicking
next every time.
C. In the main installation wizard on your browser, there should be a screen with a
D. After clicking restart, the wizard checks if you've run the certificate Import Wizard, which you've just done.
E. You should see a window that asks which certificate you want to use.
If you are setting up a single node, the setup is complete and you can start working.
Setting Up Other Nodes
When you access the Studio please navigate to: Manage Server -> Cluster. You will see something similar to this:
Incomplete Cluster view
Nodes B and C are not running yet. As soon as we start them, Node A will detect and add them to the cluster.
Now, let's bring Node B up.
A. Copy the zipped configuration
...settings.zip file to the Node B folder.
B. Extract it into the Node B folder.
C. Extract the downloaded server
RavenDB...zip folder into the Node B folder.
D. In Windows, start the RavenDB setup wizard using the
run.ps1 script. In Linux, use the
E. This time we will choose to
Continue the cluster setup for new node.
F. Run the Certificate Import Wizard again with the
admin.client...pfx that's in the Node B folder. Click
next until done.
G. In the Setup Wizard (image below),
Browse for and select the zipped
...Settings.zip file from the Node B folder.
Select node tag (B in this case).
I. Then click
Restart. A new tab with the Studio should open in your browser and when you navigate to: Manage Server -> Cluster you should see two green nodes with a green line between them.
K. Repeat the process for the remaining nodes. When all the nodes are up, you can view the updated topology in the Studio.
A Healthy Cluster
- All of the nodes in a healthy cluster should be green with green lines between them.
- If one of the nodes disconnects at any time, the RavenDB studio will show that it is red with a red line showing the disconnect.
You have successfully finished setting up a secure cluster of RavenDB servers using a Let's Encrypt certificate.
You can now register the cluster as a service in your OS (it will run in the background every time your machine starts).