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:

C# — AppHost.cs

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

XML — 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.2.1-beta.532"
  }
}

注意

The TypeScript AppHost SDK doesn’t currently expose addRavenDB or related APIs. The hosting integration is only available from C# AppHosts. If you’re using a TypeScript AppHost, model the RavenDB server with builder.addContainer(...) until TypeScript support is added.

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);

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

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.

注意

A valid RavenDB license is required. If you don’t have one yet, you can request a free Community license at ravendb.net/license/request/community. Pass the license via the RAVEN_License environment variable, or use RavenDBServerSettings to configure it.

ノート

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);

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

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);

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

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);

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

Data bind mounts rely on the host machine’s filesystem to persist the RavenDB data across container restarts. The data bind mount is mounted at the C:\RavenDb\Data on Windows (or the equivalent Unix path) on the host machine in the RavenDB container. For more information on data bind mounts, see Docker docs: Bind mounts.

ノート

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);

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

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:

C# — 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);

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

注意

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

ノート

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.