Getting started

ProvEn 2.0 makes use of Aspire, a tool from Microsoft designed for orchestrating and provisioning the entire software stack in declarative (C#) code. This handles standing up all dependencies, and running local emulators where possible. It also includes a web dashboard where services can be individually inspected, including fantastic OpenTelemetry integration.

Aspire uses OCI containers to make this possible, which relies on a container host. Container hosts require a Linux environment. On a Windows host this can be achieved using WSL.

Official prerequisite documentation can be found here.

Requirements

An overview of the requirements, relevant to ProvEn, is included below:

• You have the Azure CLI installed and must be logged in.
• A valid Azure subscription/resource group which your user has Owner permission on must be configured. This should be done in appsettings.Development.json inside the AppHost project.
• Windows Subsystem for Linux 2 (WSL2) must be enabled as a Windows feature.
• An OCI container host must be running. Podman is recommended as the easier solution, although Docker is also supported. This solution is optimised for Podman running under WSL2 (Windows Subsystem For Linux 2).
• If running on Windows, WSL2 must be configured so that containers can access the host network.

WSL Setup

Verify WSL is working by running wsl --status from a terminal. You should see an output similar to the below:

$ wsl --status
Default Distribution: Ubuntu
Default Version: 2

To configure WSL’s networking globally, add the below to $HOME/.wslconfig. Create the file if it does not already exist.

[wsl2]
# Run WSL machines on the host network
# This allows them to access anything running on the host as `localhost`.
networkingMode=mirrored

[experimental]
# Enable loopback to allow containers running under the WSL machine to access the host.
# Note containers must use `host.containers.internal` or `host.docker.internal` in place of `localhost`.
# This is resolved as the WSL machine's network, which loopback then forwards onto the Windows host.
hostAddressLoopback=true

Caution

The above WSL features are only available in Windows 11 22H2 onwards. Earlier versions of Windows will not work!

Note

Even with mirrored networking and loopback enabled, containers are still technically running on their own subnetwork. This means that anything running on the host bound to localhost will not allow connections. Instead, you should bind to 0.0.0.0 to allow connections from the container.

OCI Container Host Setup

One of Podman or Docker must be installed.

If using Podman, Aspire must be configured to use it over Docker:

[System.Environment]::SetEnvironmentVariable("ASPIRE_CONTAINER_RUNTIME", "podman", "User")

Verify the host is working by running a basic container:

podman run hello
# or
docker run hello

Run solution

Once the prerequisites are in place, start the solution by running aspire start or by using the integration from your IDE (Visual Studio, VSCode and Rider all offer official plugins).

After a few seconds the web dashboard will load up (or you will be presented with a URL). Each service will be started in turn, waiting for its dependencies.