A guide in three parts, this is the second part.
This is a three part guide if you want to install RavenDB on a virtual machine in Azure. Sounds tricky? Then you may have missed part 1.
RavenDB Setup Wizard
After accepting the EULA you will be presented with the RavenDB Setup Wizard that will step you through the process of setting up RavenDB.
RavenDB uses HTTPS (TLS/SSL) to both secure the communication to the database and to handle authentication and authorization.
To support HTTPS, RavenDB needs a server-side certificate and you can either provide your own certificate or you can let RavenDB generate it for you using Let’s Encrypt. Let’s Encrypt is a free, automated, and open certificate authority (CA).
With Let’s Encrypt the only caveat is that the certificates provided only have a 90-day lifetime. But at the same time, it is a good thing. You can read more about the reason about it here.
The nice thing with RavenDB and using Let’s encrypt is that it will automatically take care of the renewal of the certificates for you.
When you only renew your certificates once every 1-3 years, then each time is scary, because you are not really 100% sure how you did it last time. Do the things you are scared of more frequently! (certificates, deployment, rebuilding servers, rebasing and merging…)
By doing it more often, we usually will automate it and we will hopefully avoid nasty downtime due to expired certificates. Even Azure have had trouble with expired certificates: Microsoft secure Azure Storage goes down WORLDWIDE.
In our setup will use the secure Let’s Encrypt option, so we select that in the wizard.
2 - RavenDB license key
To run RavenDB you need a license key and to get started we will use the Community license that is provided by RavenDB free of charge. If you don’t have a license, then you can easily get it from here.
Enter the license and click on Next.
3 - Choose Domain
In the next step you need to choose a custom sub-domain that will be registered under the ravendb.community domain. It under this domain that the Let’s Encrypt certificate will be created for us. We choose edumenttestserver as our custom domain and that means that our database will be reachable on the following address: edumenttestserver.ravendb.community.
Click Next to continue.
4 - Node Addresses
In this step we will setup the TCP/IP ports and enter some IP-address information to complete the certificate generation.
In our setup we will enter the following information:
This screen needs some care to get right:
Node Tag This is the name of the RavenDB Node and we just enter A in our case. If you are running RavenDB in a cluster setup, then you would give each node a unique name here. This means that the full domain name to this node will be: a.edumenttestserver.ravendb.community
HTTPS port This is the port that we will use for all HTTPS communication and in our case, we use port 50000.
TCP Port This port is used for communication between nodes and clients and we choose port 50001 here.
IP-Address We enter 0.0.0.0 here. This was initially a big trouble area for me, because I initially used 127.0.0.1 here and that made RavenDB unable to receive any external traffic at all. Using 0.0.0.0 can be a security concern because this allows RavenDB to accept traffic from any of your network interfaces. To further strengthen your security it can be wise to only accept traffic from a specific network(IP-address). In our setup in Azure, this will require that you configure your VM with a static private IP-address. If you want to know more about the difference between 127.0.0.1 and 0.0.0.0, then visit this link
External IP Address As it says, we enter the public static IP of the machine RavenDB is running on and we find this address in the Azure Portal.
External ports We just enter 50000 and 50001, same as the local ports.
At the end of this step we also accept the EULA of Let’s Encrypt
Then click Next and the process of creating the DNS-record and Let’s Encrypt certificate will start.
Because it takes a while for the newly created DNS record to be recognized in Azure, you will probably get this error:
Setting up RavenDB in Let's Encrypt security mode failed.
System.InvalidOperationException: Setting up RavenDB in Let's Encrypt security mode failed. --->
System.InvalidOperationException: Validation failed. ---> System.InvalidOperationException: Failed to simulate running the server with the supplied settings using: https://a.edumenttestserver.ravendb.community:50000 ---> System.InvalidOperationException:
Cannot resolve 'a.edumenttestserver.ravendb.community' locally but succeeded resolving the address using Google's api (https://dns.google.com).
Try to clear your local/network DNS cache or wait a few minutes and try again.
Another temporary solution is to configure your local network connection to use Google's DNS server (8.8.8.8). ---> System.Net.Sockets.SocketException: No such host is known
…
Formatted for clarity)
But don’t panic! This just means that we have to wait a while (like 10-15 minutes) and then try again. The reason for this is that it takes some time for the changes in RavenDB’s DNS server to fully propagate across the internet and be visible from Azure. This is a natural thing and this is due to the caching that is done by the various DNS Servers between Azure and RavendB’s name server. Various tools exists that allows you check your DNS records from different location like: Whatsmydns.net.
What we want to achieve here is that the domain a.edumenttestserver.ravendb.community is fully reachable on the internet. Before you try again, you can always try to ping the custom domain from within the machine to check if the domain resolves properly to your static IP-address:
C:\Users\Edument>ping a.edumenttestserver.ravendb.community
Ping request could not find host a.edumenttestserver.ravendb.community. Please check the name and try again.
C:\Users\Edument>
When the DNS is ready pinging the domain should look something like:
C:\RavenDB>ping a.edumenttestserver.ravendb.community
Pinging a.edumenttestserver.ravendb.community [123.123.123.123] with 32 bytes of data: Request timed out.
( where 123.123.123.123 is the public IP-address of your machine)
We can’t proceed until the domain resolves, so we just have to wait and try again. You can always try to flush the local DNS by running:
C:\RavenDB>ipconfig /flushdns
Windows IP Configuration
Successfully flushed the DNS Resolver Cache.
C:\RavenDB>
But most of the time the changes in DNS is elsewhere. While we wait for the DNS to propagate, you can always visit Google Public DNS and query the DNS system with either an IP-address or domain name to see to what IP it should resolve to.
When all is done you should be presented with this view:
Besides presenting the view above, the very important administrator certificate is (silently) downloaded by your browser and this really caused some confusion to me during my first installation attempts of RavenDB. You can find this certificate in your browser downloads folder:
Click on the Restart server button to continue.
The administrator certificate
The certificate downloaded by your browser is your key to login to the database as administrator, so copy this file to a secure location because without it you can’t login. If you do lose it, then you can via the RavenDB CLI regenerate a new administrator certificate.
By default, the installer will add this certificate to the Windows certificate store and when you browse to RavenDB you will be presented with this dialog, in which you choose what certificate you want to use.
If you are using Firefox, then you need to manually import this certificate into the browser. Visit Security : Common Errors & FAQ for more information.
If you are presented with this error:
Then the administrator certificate hasn’t been installed correctly. To install it, unzip the edumenttestserver.Cluster.Settings.zip file:
Then double-click on the Personal Information Exchange (.pfx) file and then just click next on all the steps to complete the import wizard. Then restart your browser and try again to navigate to the database, in our case: https://a.edumenttestserver.ra...
After that you will be presented with the certificate dialog as shown above and be able to login as administrator to the database.
By Tore Nestenius