Set up RavenDB in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire RavenDB Hosting integration. It enumerates the AppHost APIs that you use to model RavenDB server and database resources in your AppHost project.

If you’re new to the RavenDB integration, start with the Get started with RavenDB integrations guide. For how consuming apps read the connection information this page exposes, see Connect to RavenDB.

Installation

The Aspire RavenDB hosting integration models the RavenDB server as the RavenDBServerResource type and the database as the RavenDBDatabaseResource type. To start building an Aspire app that uses RavenDB, install the 📦 CommunityToolkit.Aspire.Hosting.RavenDB NuGet package:

C#

Terminal

aspire add CommunityToolkit.Aspire.Hosting.RavenDB

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.RavenDB@*

AppHost.csproj

<PackageReference Include="CommunityToolkit.Aspire.Hosting.RavenDB" Version="*" />

TypeScript

Terminal

aspire add CommunityToolkit.Aspire.Hosting.RavenDB

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the RavenDB hosting integration package:

aspire.config.json

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.RavenDB": "13.4.0"
  }
}

Add RavenDB server resource and database resource

Once you’ve installed the hosting integration in your AppHost project, you can add a RavenDB server resource and then add a database resource:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer");
var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const ravenServer = await builder.addRavenDB("ravenServer");
const ravendb = await ravenServer.addDatabase("ravendb");

const apiService = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await apiService.withReference(ravendb);
await apiService.waitFor(ravendb);

await builder.build().run();

1. When Aspire adds a container image to the app host, as shown in the preceding example with the docker.io/ravendb/ravendb image, it creates a new RavenDB instance on your local machine.

2. The AddDatabase call registers a database sub-resource named ravendb on the server. By default, the database name matches the resource name. You can pass a different database name as the second argument: ravenServer.AddDatabase("ravendb", databaseName: "mydb").

3. The AppHost reference call configures a connection in the consuming project named after the referenced database resource, such as ravendb in the preceding example.

Note

Depending on your usage, RavenDB may require a license. For development, request a free Developer license. For production, see the available licenses — including a free Community license that’s eligible for commercial use. Pass your license via the RAVEN_License environment variable, or with RavenDBServerSettings from a C# AppHost.

Note

When you reference a RavenDB resource from the AppHost, Aspire makes several properties available to the consuming project, such as the server URI, hostname, port, and database name. For a complete list of these properties and per-language connection examples, see Connect to RavenDB.

Add RavenDB database resource with auto-create

By default, AddDatabase registers the database in the Aspire model but does not create it in RavenDB automatically. Pass ensureCreated: true to have Aspire create the database on startup if it does not already exist:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer");
var ravendb = ravenServer.AddDatabase("ravendb", ensureCreated: true);

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const ravenServer = await builder.addRavenDB("ravenServer");
const ravendb = await ravenServer.addDatabase("ravendb", { ensureCreated: true });

const apiService = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await apiService.withReference(ravendb);
await apiService.waitFor(ravendb);

await builder.build().run();

Add RavenDB server resource with data volume

Add a data volume to the RavenDB server resource to persist data outside the lifecycle of its container:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
    .WithDataVolume();

var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const ravenServer = await builder.addRavenDB("ravenServer");
await ravenServer.withDataVolume();

const ravendb = await ravenServer.addDatabase("ravendb");

const apiService = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await apiService.withReference(ravendb);
await apiService.waitFor(ravendb);

await builder.build().run();

The data volume is mounted at the /var/lib/ravendb/data path in the RavenDB container. When a name parameter isn’t provided, the name is generated at random. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Add RavenDB server resource with data bind mount

Add a data bind mount to the RavenDB server resource as an alternative to a named volume:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
    .WithDataBindMount(source: @"C:\RavenDb\Data");

var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const ravenServer = await builder.addRavenDB("ravenServer");
await ravenServer.withDataBindMount("C:\\RavenDb\\Data");

const ravendb = await ravenServer.addDatabase("ravendb");

const apiService = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await apiService.withReference(ravendb);
await apiService.waitFor(ravendb);

await builder.build().run();

Data bind mounts rely on the host machine’s filesystem to persist the RavenDB data across container restarts. The bind mount maps the host path C:\RavenDb\Data (on Windows, or the equivalent Unix path) to the /var/lib/ravendb/data directory inside the RavenDB container. For more information on data bind mounts, see Docker docs: Bind mounts.

Note

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Add RavenDB server resource with log volume

Add a named volume for the RavenDB logs directory:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
    .WithDataVolume()
    .WithLogVolume();

var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const ravenServer = await builder.addRavenDB("ravenServer");
await ravenServer.withDataVolume();
await ravenServer.withLogVolume();

const ravendb = await ravenServer.addDatabase("ravendb");

const apiService = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await apiService.withReference(ravendb);
await apiService.waitFor(ravendb);

await builder.build().run();

The log volume is mounted at the /var/log/ravendb/logs path in the RavenDB container. You can also use WithLogBindMount(source: @"C:\RavenDb\Logs") to bind-mount a host directory for logs.

Add secured RavenDB server resource

To create a secured RavenDB instance using a pre-configured settings.json file or a self-signed certificate, use RavenDBServerSettings.Secured or RavenDBServerSettings.SecuredWithLetsEncrypt:

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var serverSettings = RavenDBServerSettings.SecuredWithLetsEncrypt(
    domainUrl: "https://mycontainer.development.run",
    certificatePath: "/etc/ravendb/security/cluster.server.certificate.mycontainer.pfx");

var ravenServer = builder.AddRavenDB("ravenSecuredServer", serverSettings)
    .WithBindMount("C:/RavenDB/Server/Security", "/etc/ravendb/security", isReadOnly: false);

var ravendb = ravenServer.AddDatabase("ravendbSecured");

builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(ravendb)
    .WaitFor(ravendb);

builder.Build().Run();

Caution

Ensure the certificate path is accessible to the container by bind-mounting the host certificate directory to /etc/ravendb/security.

Note

The RavenDBServerSettings-based overload of AddRavenDB is only available from C# AppHosts. It includes certificate and licensing configuration that is not compatible with the polyglot TypeScript AppHost.

Connection properties

For the full reference of RavenDB connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to RavenDB.

Hosting integration health checks

The RavenDB hosting integration automatically adds a health check for both the server resource and each database resource, verifying that the instance is running and reachable. The hosting integration relies on the 📦 AspNetCore.HealthChecks.RavenDB NuGet package.