Set up KurrentDB in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire KurrentDB Hosting integration. It enumerates the AppHost C# 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:

aspire add communitytoolkit-kurrentdb

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

Select an integration to add:

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

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

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

Or, choose a manual installation approach:

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

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

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:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/eventstore/eventstore image, it creates a new KurrentDB instance on your local machine.
The AppHost reference call configures a connection in the consuming project named after the referenced KurrentDB resource, such as kurrentdb in the preceding example.

Add KurrentDB resource with data volume

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

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.