Set up KurrentDB in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire KurrentDB Hosting integration. It enumerates the AppHost APIs that you use to model a KurrentDB resource in your AppHost project.

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

Installation

To start building an Aspire app that uses KurrentDB, install the 📦 CommunityToolkit.Aspire.Hosting.KurrentDB NuGet package:

C#

Aspire CLI

Aspire CLI — Add CommunityToolkit.Aspire.Hosting.KurrentDB package

aspire add communitytoolkit-kurrentdb

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

Aspire CLI — Example output prompt

Select an integration to add:

> communitytoolkit-kurrentdb (CommunityToolkit.Aspire.Hosting.KurrentDB)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.Hosting.KurrentDB package reference

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

Or, choose a manual installation approach:

AppHost.cs

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

AppHost.csproj

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

TypeScript

Terminal

aspire add CommunityToolkit.Aspire.Hosting.KurrentDB

Learn more about aspire add in the command reference.

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

aspire.config.json

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.KurrentDB": "*"
  }
}

Add KurrentDB resource

Once you’ve installed the hosting integration in your AppHost project, you can add a KurrentDB resource as shown in the following example:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.kurrent.io/kurrent-latest/kurrentdb image, it creates a new KurrentDB instance on your local machine.

2. The AppHost reference call configures a connection in the consuming project named after the referenced KurrentDB resource, such as kurrentdb in the preceding example.

Note

When you reference a KurrentDB resource from the AppHost, Aspire makes several properties available to the consuming project, such as connection URIs, hostnames, and port numbers. For a complete list of these properties and per-language connection examples, see Connect to KurrentDB.

Add KurrentDB resource with data volume

Add a data volume to the KurrentDB resource as shown in the following example:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb")
    .WithDataVolume();

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");
await kurrentdb.withDataVolume();

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

The data volume is used to persist KurrentDB data outside the lifecycle of its container. The data volume is mounted at the /var/lib/kurrentdb path in the KurrentDB container, and 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 KurrentDB resource with data bind mount

Add a data bind mount to the KurrentDB resource as shown in the following example:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb")
    .WithDataBindMount(source: @"C:\KurrentDB\Data");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

TypeScript

apphost.mts

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

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");
await kurrentdb.withDataBindMount("C:\\KurrentDB\\Data");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

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.

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

Hosting integration health checks

The KurrentDB hosting integration automatically adds a health check for the KurrentDB resource. The health check verifies that the KurrentDB instance is running and that a connection can be established to it. The health check is wired into the /health HTTP endpoint, where all registered health checks must pass before the app is considered ready to accept traffic.