see on GitHub

RavenDB Setup Walkthrough

To make the setup process as smooth as possible, we introduced the "Setup Wizard", a step-by-step guide to help you configure your desired level of security and easily deploy a secured cluster.

You have 4 options to choose from:

  1. Secure Setup with a Let's Encrypt certificate
  2. Secure Setup with your own certificate
  3. Unsecured Setup
  4. Manual Setup

When running the RavenDB server for the first time, you will be redirected to the setup wizard welcome screen where you can choose your preferred option.

Figure 1. Welcome Screen

This section explains how to follow the setup wizard. It does not go into detail about security concerns. If you wish to learn about how authentication and authorization work in RavenDB or more about security in general, please read the relevant security section.


Secure Setup with a Let's Encrypt Certificate

Let's Encrypt is a free, automated, and non-profit certificate authority. It will generate a certificate for your domain (or website) as long as you can prove that you own it.

We want to make it as easy as possible for you to start RavenDB with a valid trusted certificate from the very beginning and to stay secure through your entire application lifecycle, starting from early stages of development, ending on production and day-to-day usage.

During the wizard, RavenDB will give you a free subdomain under "dbs.local.ravendb.net". It lets 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, but you can always update the DNS records by running the setup wizard.

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 manually configure the server with it.

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 nitpicks of setting up DNS records, generating certificates and doing their renewals. Because of those 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 setup and running with a minimum of fuzz, but 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 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. This process will associate your license with the chosen subdomain to ensure that valid certificates can only be generated by a single license holder.

Figure 2. Enter License

The next step is to claim your domain.

Figure 3. Claim Domain

In the next screen, you can choose the IP address and port that your server will listen to.

Important

If you wish to setup a cluster, this is the place to add nodes to the cluster and choose their addresses. You should run the setup wizard only on the first node in the cluster and not on each of them separately. The first node will generate the required configuration for the entire cluster, and will provide detailed guidance on how to setup the additional nodes.

In the following screenshot, we show an example of constructing a cluster for local development:

Figure 4. Configure Cluster

All 3 nodes will run on the local machine as 3 different processes:

  • Node A (https://a.3cpo.dbs.local.ravendb.net) will listen to 127.0.0.1 on port 8080.
  • Node B (https://b.3cpo.dbs.local.ravendb.net) will listen to 127.0.0.2 on port 8080.
  • Node C (https://c.3cpo.dbs.local.ravendb.net) will listen to 127.0.0.3 on port 8080.

A real life scenario will be to have each node on its own machine. In that case, you would enter the actual IP address the node will listen to on that machine. IP addresses may be changed at a later time by running the setup wizard again which will update the DNS records at "dbs.local.ravendb.net".

A common scenario for running an internal cluster will be:

  • Node A (https://a.3cpo.dbs.local.ravendb.net) will listen to 10.0.0.84 on port 443.
  • Node B (https://b.3cpo.dbs.local.ravendb.net) will listen to 10.0.0.75 on port 443.
  • Node C (https://c.3cpo.dbs.local.ravendb.net) 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. RavenDB also ensures that the Let's Encrypt certificate is refreshed automatically as needed.

Important

You need to make sure that the IP/port is available. On the local machine, the setup will check the port availability and validate the IP address. However, on the other machines in the cluster, you'll need to verify that beforehand. When using port 443, you need to ensure that it hasn't already been taken by other applications like Skype, IIS, Apache, etc.

When you click next, the wizard will establish a connection with Let's Encrypt to obtain a valid certificate for the entire cluster. This process usually takes a few minutes.

Figure 5. Finishing Up

When finished you will receive a ZIP file containing all of the cluster configuration files that include the server and client certificates, and a settings.json file for each node.

Figure 6. Configuration Completed

Click the "Restart Server" button and wait until the browser redirects you to the new URL (in our example, it's "https://a.3cpo.dbs.local.ravendb.net").

If you checked the relevant box in the previous stage, 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 didn't check the box, before you continue please register the client certificate in the OS store or import it to the browser.

Figure 7. Restart and choose certificate

When you access the studio please navigate to: Manage Server > Cluster. You will see something similar to this:

Figure 8. Incomplete Cluster

Nodes B and C are not running yet. As soon as we start them, node A will detect it and add them to the cluster.

Now, let's configure nodes B and C.

In the ZIP file you have a folder for each node which includes a settings.json and a server certificate. For each node, simply copy these 2 files (overwrite existing) to that node's RavenDB server folder and start the server.

When nodes B and C are up, go back to the studio and see that the topology of the cluster was updated.

Figure 9. Complete Cluster

You have successfully finished setting up a secure cluster of RavenDB servers using a Let's Encrypt certificate.


Secure Setup with Your Own Certificate

In RavenDB, users can provide their own server certificate. The certificate can be issued by a trusted SSL vendor or it can be a self-signed certificate. In the latter case, it's the user's responsibility to have the self-signed CA registered in the OS stores on all the relevant machines.

RavenDB will only accept server certificates which contain the private key and have the following fields:

  • KeyUsage: CertSign, CRLSign, DigitalSignature, KeyEncipherment
  • ExtendedKeyUsage: Client Authentication, Server Authentication

If you wish to use the setup wizard to construct a cluster, you must use the same certificate for all nodes. If you wish to use a different certificate for each node, it's possible only through manual setup.

A wildcard certificate is probably the easiest way. Another option is to issue a certificate which contains all the domains of all the cluster nodes as "Subject Alternative Names" (SANs).

After choosing the Secure Setup with your own certificate option, you are required to upload the certificate and click next. In the example, we will use the *.ravendb.example.com wildcard certificate.

Figure 1. Upload Certificate

In the next screen, you can choose the IP address and port that your server will listen to.

Important

If you wish to setup a cluster, this is the place to add nodes to the cluster and choose their addresses. You should run the setup wizard only on the first node in the cluster and not on each of them separately. The first node will generate the required configuration for the entire cluster, and will provide detailed guidance on how to setup the additional nodes.

In the following screenshot, we show an example of constructing such a cluster:

  • Node A (https://a.ravendb.example.com) will listen to 10.0.0.84 on port 443.
  • Node B (https://b.ravendb.example.com) will listen to 10.0.0.75 on port 443.
  • Node C (https://c.ravendb.example.com) will listen to 10.0.0.91 on port 443.
Figure 2. Configure Cluster

Important

You need to make sure that the IP/port is available. On the local machine, the setup will check the port availability and validate the IP address. However, on the other machines in the cluster, you'll need to verify that beforehand. When using port 443, you need to ensure that it hasn't already been taken by other applications like Skype, IIS, Apache, etc.

When finished, you will receive a ZIP file containing all of the cluster configuration files including the server and client certificates, and a settings.json file for each node.

Figure 3. Configuration Completed

At this point, click the "Restart Server" button, and wait until the browser redirects you to the new URL (in the example it's "https://a.ravendb.example.com").

If you checked the relevant box in the previous stage, 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 didn't check the box, please register the client certificate in the OS store or import it to the browser before you continue.

Figure 4. Restart and choose certificate

When you access the studio please navigate to: Manage Server > Cluster. You will see something similar to this:

Figure 5. Incomplete Cluster

Nodes B and C are not running yet. As soon as we start them, node A will detect it and add them to the cluster.

Now let's configure nodes B and C.

In the ZIP file you have a folder for each node which includes a settings.json and a server certificate. For each node, simply copy these 2 files (overwrite existing) to that node's RavenDB server folder and start the server.

When nodes B and C are up, go back to the studio and see that the topology of the cluster was updated.

Figure 6. Complete Cluster

You have successfully finished setting up a secure cluster of RavenDB servers using you own wildcard certificate.

Unsecured Setup

Setting up the server in an unsecured mode requires you to choose the IPs and port that the server will listen to and an optional "Public Server URL".

Note

In unsecured mode all security features are disabled (authentication, authorization and encryption).

If you choose to develop only on your local machine, enter the private IP addresses and port. When the setup wizard completes, the server will restart and listen to these addresses.

The following screenshot shows a simple local configuration. The server in the example will be accessible at "http://127.0.0.1:8080" or "http://localhost:8080".

Figure 1. Complete Cluster

If you choose to open the server to the outside network or Internet, you can enter public IP addresses and a "Public Server URL".

Danger

When choosing to listen to an outside network, the RavenDB server runs in an unsafe mode. Authentication is off. Anyone who can access the server using the configured IP address will be granted administrative privileges.

The following screenshot shows a configuration for listening to a public IP address. The server in the example will be accessible from both the chosen IP address and the "Public Server URL".

Figure 2. Complete Cluster

When you are done configuring the server, click next and then restart. After a few seconds, the server is ready and accessible.

Figure 3. Complete Cluster

You can access the studio by entering the URL in the browser (in the example it's "http://127.0.0.1:8080" or "http://localhost:8080" ).

Figure 4. Complete Cluster

You have successfully finished setting up a RavenDB server.

To construct a cluster locally, unzip the downloaded RavenDB package to more folders, as many as the number of nodes you want. Each node will run in its own process. For each node, complete the setup wizard just like we did now, with different private IP addresses.

To construct a cluster in a network, complete the setup wizard in each machine (node) separately.

Once all the servers are up and running, building the cluster is simple. Access the studio, go to Manage Server > Cluster, and add nodes to the cluster by their URL.

Read more about Clustering here.

Manual Setup

If none of the above setup options work for you, it is possible to configure the server manually using the 'settings.json' file which is located in the server folder. To disable the setup wizard, change the 'Setup.Mode' value to 'None' and then run the server.

Read the Security Section to learn about security in RavenDB and how to enable the security features.

Read the Configuration Section to learn more about using 'settings.json' and see a list of configuration options.