---
title: "Server: Running an Embedded Instance"
url: "https://docs.ravendb.net/6.2/server/embedded"
version: "6.2"
language: "java"
---

# Server: Running an Embedded Instance

> Client language: Java. Also available for [C#](https://docs.ravendb.net/6.2/server/embedded.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

## Overview

RavenDB makes it very easy to be embedded within your application, with RavenDB Embedded package you can integrate your RavenDB server with few easy steps.

```java
EmbeddedServer.INSTANCE.startServer();

try (IDocumentStore store = EmbeddedServer.INSTANCE.getDocumentStore("Embedded")) {
  try (IDocumentSession session = store.openSession()) {
      // your code here
  }
}
```

## Prerequisites

There is one prerequsite and one recommendation for the Embedded package:

Prerequsite:

- **.NET Core runtime** must be installed manually

> **Note:** .NET Core Runtime {#net-core-runtime}
>
> RavenDB Embedded **does not include .NET Core runtime required for it to run**.
>
> By default the `ServerOptions.FrameworkVersion` is set to the .NET Core version that we compiled the server with and `ServerOptions.DotNetPath` is set to `dotnet` meaning that it will require to have it declared in PATH.
>
> We highly recommend using the .NET Core framework version defined in `ServerOptions.FrameworkVersion` for proper functioning of the Server. The .NET Core runtime can be downloaded from [here](https://dotnet.microsoft.com/download).

## Getting Started

### Installation

- Create a new project
- Add package [net.ravendb:ravendb-embedded](https://search.maven.org/search?q=a:ravendb-embedded) as dependency

### Starting the Server

RavenDB Embedded Server is available under `EmbeddedServer.INSTANCE`. In order to start it call `startServer` method.

```java
// Start RavenDB Embedded Server with default options
EmbeddedServer.INSTANCE.startServer();
```

For more control on how to start the server just pass to `startServer` method a `ServerOptions` object and that\`s it.

> **Info:** ServerOptions {#serveroptions}
>
> | Name | Type | Description |
> | - | - | - |
> | **frameworkVersion** | String | The .NET Core framework version to run the server with |
> | **dataDirectory** | String | Indicates where your data should be stored |
> | **dotNetPath** | String | The path to exec `dotnet` (if it is in PATH, leave it) |
> | **targetServerLocation** | String | The path to extract server binaries |
> | **acceptEula** | boolean | If set to `false`, will ask to accept our terms & conditions |
> | **erverUrl** | String | What address we want to start our server (default `127.0.0.1:0`) |
> | **maxServerStartupTimeDuration** | `Duration` | The timeout for the server to start |
> | **commandLineArgs** | `List&lt;String&gt;` | The [command lines arguments](https://docs.ravendb.net/6.2/server/configuration/configuration-options.md#command-line-arguments) to start the server with |

```java
ServerOptions serverOptions = new ServerOptions();
// target location of RavenDB data
serverOptions.setDataDirectory("C:\\RavenData");
serverOptions.setServerUrl("http://127.0.0.1:8080");

// location where server binaries will be extracted
serverOptions.setTargetServerLocation("c:\\RavenServer");
EmbeddedServer.INSTANCE.startServer(serverOptions);
```

> **Note**
>
> Without the `ServerOptions`, RavenDB server will start with a default values on `127.0.0.1:{Random Port}`

### Security

RavenDB Embedded support running a secured server.
Just run `secured` method in `ServerOptions` object.

We have two overloads to `secured`:

```java
ServerOptions serverOptions = new ServerOptions();
serverOptions.secured("PathToCertificate", "CertificatePassword");
```

The first way to enable authentication is to set certificate with the path to your .pfx
server certificate. You may supply the certificate password using certPassword.

```java
ServerOptions serverOptions = new ServerOptions();
serverOptions.secured("powershell",
  "c:\\secrets\\give_me_cert.ps1",
  "a909502dd82ae41433e6f83886b00d4277a32a7b",
  clientCertificate,
  "PathToCaCertificateFile");
```

This option is useful when you want to protect your certificate (private key) with other solutions such as "Azure Key Vault", "HashiCorp Vault" or even Hardware-Based Protection.
RavenDB will invoke a process you specify, so you can write your own scripts / mini programs and apply whatever logic you need. It creates a clean separation between RavenDB and the secret store in use.
RavenDB expects to get the raw binary representation (byte array) of the .pfx certificate through the standard output.
In this options you can control on your client certificate and to use in a different certificate for your client.

### Document Store

After starting the server you can get the DocumentStore from the Embedded Server and start working with RavenDB.
Getting the DocumentStore from The Embedded Server is pretty easy you only need to call `getDocumentStore` with the name of the database you like to work with.

```java
EmbeddedServer.INSTANCE.getDocumentStore("Embedded");
```

For more control on the process you can call the methods with `DatabaseOptions` object.

> **Info:** DatabaseOptions {#databaseoptions}
>
> | Name | Type | Description |
> | - | - | - |
> | **DatabaseRecord** | DatabaseRecord | Instance of `DatabaseRecord` containing database configuration |
> | **SkipCreatingDatabase** | boolean | If set to true, will skip try creating the database |

```java
DatabaseRecord databaseRecord = new DatabaseRecord();
databaseRecord.setDatabaseName("Embedded");
DatabaseOptions databaseOptions = new DatabaseOptions(databaseRecord);
EmbeddedServer.INSTANCE.getDocumentStore(databaseOptions);
```

### Get Server URL

The `getServerUri` method can be used to retrieve the Embedded server URL. It must be called after server was started, because it waits for the server initialization to complete.
The URL can be used for example for creating a custom document store, omitting the `getDocumentStore` method entirely.

```java
String serverUri = EmbeddedServer.INSTANCE.getServerUri();
```

## Remarks

- You can have only one instance of `EmbeddedServer`
- Method `EmbeddedServer.INTANCE.openStudioInBrowser()` can be used to open an browser instance with Studio

## See also

- [TestDriver](https://docs.ravendb.net/6.2/start/test-driver.java.md)
- [TestDriver Licensing](https://docs.ravendb.net/6.2/start/test-driver.java.md#licensing)
- [Collect information for support](https://docs.ravendb.net/6.2/server/troubleshooting/collect-info.md)
