Chapter 8. Deploying RavenDB

Using RavenDB outside the development environment implies the need to know how to deploy RavenDB to this new environment. This chapter provides an overview of the deployment strategies you might plan for the RavenDB server.

Every organization is unique. This chapter aims to provide information to help you define the best deployment strategies and plans for your organization and gives a description of each deployment approach, associated benefits, assumptions, and risks.

In this chapter, we will cover how to run RavenDB:

• As a Windows Service

• As an IIS application

• In Embedded mode

RavenDB deployment strategies

Until now, to launch the RavenDB server, we used the Start.cmd command file or executed the Raven.Server.exe file directly in Windows Explorer. This running mode is called console mode, and it might be good for testing and developing purposes; however, this running mode is not recommended for a production environment.

RavenDB gives you three other deployment options for getting your data from the server. The first option is the ability to run as a Windows Service, the second option is the ability to be hosted in Internet Information Server (IIS), and the last option, called Embedded mode, allows you to embed the RavenDB server into your application or to run it completely in the memory.

Note

RavenDB Version 2.5 will provide an MSI installer which will allow efficient installation and configuration of RavenDB.

Running RavenDB as a Windows Service

RavenDB offers the possibility to run as a Windows Service. Windows Services are designed to allow long-running executable applications that run in their own Windows sessions.

When running RavenDB as a Windows Service, it doesn't show any user interface and can be automatically started when the computer boots; it can also be stopped and restarted. After a RavenDB service is installed, it must be started, and it will remain active until it is manually stopped or the computer on which it is running is shut down.

A RavenDB service can be set up to start automatically or manually. Starting automatically means that it will be started when the computer on which it is installed is rebooted or first turned on. If RavenDB is set up to start manually, that means it must be started (manually) by a user.

You can run a RavenDB service in a security context of a specific user account that is different from the logged-on or the default computer account. Also, it can be...

Time for action – running RavenDB as a Windows Service

You will now manually install and run RavenDB as a Windows Service using the command line. Then, you will verify that it appears in the Windows Services Management Console, from where you can stop and restart it:

1. Ensure that RavenDB is not running.

2. Open a new command prompt window using administrator privileges.

3. Change your current directory to the ~\Server folder of the RavenDB installation directory.

4. Run the Raven.Server.exe file using the /install parameter in the command line:

   

5. When the install process completes, enter services.msc to open the Services Management Console.

6. Locate the RavenDB service and ensure it is successfully installed and running:

   

   Tip

   The RavenDB service will start automatically after the install process terminates. To change the startup type (Automatic or Manual), double-click on the RavenDB service in the Services Console Management and change it to the desired type from the Startup Type drop-down list.

7. Open RavenDB Management...

Time for action – uninstalling the RavenDB service

You will now manually uninstall the RavenDB service using the command line and then open the Services Management Console to verify that it has been removed from the Windows Services list:

1. Open a new command prompt window using administrator privileges.

2. Change your current directory to the~\Server folder of the RavenDB installation directory.

3. Run the Raven.Server.exe file using the/uninstall parameter in the command line.

   

4. Once the uninstall process completes, enter services.msc to open the Services Management Console to verify that the RavenDB service has been removed.

What just happened?

You used the /uninstall command-line parameter to manually uninstall the RavenDB service from the Windows Services list.

To perform the service uninstall, you launched Raven.Server.exe /uninstall, which will stop the RavenDB service and remove it from the Windows Services list.

RavenDB and IIS

RavenDB supports running as an IIS application, or from an IIS virtual directory under an IIS application. IIS stands for Internet Information Services, and it is a secure and scalable web server provided with Windows operating systems.

When running RavenDB as an IIS application or from a virtual directory, it can be managed from the IIS Manager, and you may use the IIS management tool to configure, start, stop, and restart the web application.

Running RavenDB on IIS offers the full benefits of being managed in IIS, which allows you to set memory limits, monitor via standard tools, use SSL, and so on.

In IIS mode, RavenDB uses configuration from the Web.config file in the physical directory to which the directory is mapped as well as in any child directories in that physical directory.

Running RavenDB from an IIS virtual directory

A virtual directory is a path that you specify in IIS and map to a physical directory on a local or remote server. Then, this path becomes a part of...

Time for action – running RavenDB from an IIS virtual directory

You will now manually install and run RavenDB from an IIS virtual directory. Then, you will open Management Studio to access RavenDB:

1. Open the Internet Information Services Manager.

   Note

   IIS is not enabled by default on Windows operating systems. To use the IIS Manager, you must install or enable IIS on your computer. To learn more about how to install IIS, follow this link: http://technet.microsoft.com/En-us/library/cc725762.aspx.

2. Right-click on the Sites node and choose Add Website....

   

3. Enter RavenDB for the Site name then click on the Select button to select the appropriate Application pool (basically ASP.Net v4.5):

   

   Note

   Depending on your operating system version and IIS configuration, you may not have the same application pools listed in this screen capture. Basically, you need to select the .Net v4.5 application pool.

   You may create a new application pool and set it to .NET 4.5 Integrated Pipeline then assign it to the new website...

Time for action – running RavenDB as an IIS application

You will, manually install and run RavenDB as an IIS application. This application will use its own application pool and will run in its own security context. Then, you will open Management Studio to access RavenDB:

1. Open your Computer Management Console, add a new user called RavenDB, and make it a member of the IIS_IUSRS group.

2. Open the Internet Information Services Manager.

3. Right-click on the Application Pools node and choose Add Application Pool....

4. Name the new application pool RavenDBApplicationPool, select .NET Framework v4.0.30319, and click on the OK button:

   

5. Right-click on the Sites node then choose Add Website... and name it RavenDBAppli.

6. Set the Application pool to RavenDBApplicationPool.

7. Set the Physical path of the IIS site to the ~\web directory of the RavenDB installation folder and the Binding Port to 8080 (if available).

8. Click on the Connect As... button and set the credentials to the RavenDB account you just created:

   

9. Click on...

RavenDB Embedded mode

RavenDB supports embedding into your .NET application. That means your application will contain all necessary files to run RavenDB, which will be part of your application. Running RavenDB in Embedded mode is similar to running it in Console mode (launching the Raven.Server.exe file). The main difference is that RavenDB will start automatically in Embedded mode, while you need to start it manually in Console mode. Also, when running RavenDB in Embedded mode, you can interact programmatically with the server instance.

Embedding RavenDB

To run RavenDB in embedded mode, you need to reference the RavenDB Embedded Client in your .NET application. You may add this reference either via the NuGet Package Manager (package name RavenDB Embedded) or by taking the files from the ~\EmbeddedClient folder in the RavenDB distribution package.

After the RavenDB Embedded Client is referenced in your application, you need to create a new instance of the EmbeddableDocumentStore object. Then...

Time for action – running RavenDB in Embedded mode

You will now create a new application, refer the RavenDB Embedded Client, and run RavenDB in Embedded mode. Then, you will open Management Studio to access the embedded RavenDB and create a new database and explore the RavenDB data folder:

1. Open Visual Studio, create a new Console Application project, and name it EmbeddedRavenDB.

2. Use the NuGet Package Manager to add a reference to the RavenDB Embedded package (it will add two packages automatically, RavenDB Client and RavenDB Database).

   

3. Modify the Program class to make it look like the following code snippet:

   

4. Press F5 to build and run the EmbeddedRavenDB project.

5. Open Management Studio, create a new database, and explore the server data directory.

What just happened?

You just created the EmbeddedRavenDB Visual Studio project to run RavenDB in Embedded mode.

In order to run RavenDB in Embedded mode, you refer the RavenDB Embedded assemblies using the NuGet Package Manager. Once you add the reference...

Time for action – running RavenDB inmemory

You will now modify the EmbeddedRavenDB project to run RavenDB in-memory:

1. Open the EmbeddedRavenDB project in Visual Studio.

2. Modify the Program class to look like the following code snippet:

   

3. Press F5 to build and run the EmbeddedRavenDB project.

4. Open Management Studio to create a new database and explore the server data directory.

What just happened?

You modified the EmbeddedRavenDB Visual Studio project to run RavenDB in-memory.

In order to run RavenDB in-memory you modified the Program class to set the RunInMemory flag to true while creating the new instance of the EmbeddableDocumentStore object (lines 24).

The other pieces of code remain the same for now, once you call the Initialize() method, RavenDB will start and run in-memory, and any new created database will no longer be stored on your disk.

Pop quiz – searching the right way

Q1. When you try to create a database on your IIS hosted RavenDB, you get the following error: The remote server returned...

Summary

In this chapter, we learned the different options for deploying RavenDB, and for each option, we covered how to deploy and run RavenDB and the associated benefits. Specifically, we covered RavenDB deployment strategies and how to run RavenDB as a Windows Service as well as how to host RavenDB in an Internet Information Server (IIS).

Also, we covered the Embedded mode and learned how to embed RavenDB inside your application as well as how to embed it in-memory.

In the next chapter, we will talk about RavenDB sharding and how it can help you to scale-out your RavenDB server.