RavenDB Hosting integration reference

⭐ Community Toolkit

To get started with the Aspire RavenDB integrations, follow the Get started with RavenDB integrations guide.

This article includes full details about the Aspire RavenDB Hosting integration.

Installation

The Aspire RavenDB hosting integration models the RavenDB server as the RavenDBServerResource type and the database as the RavenDBDatabaseResource type. To access these types and APIs, install the 📦 CommunityToolkit.Aspire.Hosting.RavenDB NuGet package in the AppHost project:

aspire add communitytoolkit-ravendb

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-ravendb (CommunityToolkit.Aspire.Hosting.RavenDB)
> Other results listed as selectable options...

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

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

Add RavenDB server resource and database resource

To set up RavenDB in your AppHost project, call the AddRavenDB extension method to add a RavenDB server resource, then call AddDatabase on the server resource to add a database:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, build and run the app...

Add RavenDB server resource with data volume

To add a data volume to the RavenDB server resource, call the WithDataVolume method:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

The data volume remains available after the container’s lifecycle ends, preserving RavenDB data. The data volume is mounted at the /var/lib/ravendb/data path in the RavenDB container and when a name parameter isn’t provided, the name is generated at random.

Add RavenDB server resource with data bind mount

To add a data bind mount to the RavenDB server resource, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

Data bind mounts rely on the host machine’s filesystem to persist the RavenDB data across container restarts.

Add secured RavenDB server resource

To create a new secured RavenDB instance using settings from a pre-configured settings.json file or a self-signed certificate, use the RavenDBServerSettings.Secured method or RavenDBServerSettings.SecuredWithLetsEncrypt for Let’s Encrypt configurations:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Hosting integration health checks

The RavenDB hosting integration automatically adds a health check for the RavenDB server resource, verifying that the server is running and reachable.