Java integration

⭐ Community Toolkit

The Aspire Java hosting integration enables you to run Java applications, including Spring Boot applications, alongside your Aspire projects in the Aspire app host.

Hosting integration

To get started with the Aspire Java hosting integration, install the CommunityToolkit.Aspire.Hosting.Java NuGet package in the app host project.

aspire add communitytoolkit-java

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

Select an integration to add:

> communitytoolkit-java (CommunityToolkit.Aspire.Hosting.Java)
> Other results listed as selectable options...

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

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

Add Spring Boot app

To add a Spring Boot application to your app host, use the AddSpringApp extension method:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    workingDirectory: "../spring-app",
    otelAgentPath: "../agents/opentelemetry-javaagent.jar")
    .WithHttpEndpoint(port: 8080);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(javaApp);

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

The AddSpringApp method requires:

name: The name of the resource in the Aspire dashboard
workingDirectory: The path to the directory containing your Spring Boot application
otelAgentPath: The path to the OpenTelemetry Java agent JAR file

Container hosting

For production scenarios, you can host Java applications in containers. Use JavaAppContainerResourceOptions to specify container-specific settings:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    new JavaAppContainerResourceOptions
    {
        OtelAgentPath = "../agents/opentelemetry-javaagent.jar",
        ContainerImageName = "my-spring-app:latest",
        ContainerRegistry = "myregistry.azurecr.io"
    })
    .WithHttpEndpoint(port: 8080);

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

Executable hosting

For local development, you can run Java applications as executables using JavaAppExecutableResourceOptions:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    new JavaAppExecutableResourceOptions
    {
        ApplicationName = "spring-app",
        OtelAgentPath = "../agents/opentelemetry-javaagent.jar",
        WorkingDirectory = "../spring-app"
    })
    .WithHttpEndpoint(port: 8080);

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

Certificate trust (Linux/macOS)

On Linux and macOS, you may need to add additional configuration to trust the Aspire development certificates. Add the following to your Spring Boot application’s application.properties:

server.ssl.trust-store=/path/to/aspire/dev/certificate.p12
server.ssl.trust-store-password=your-password

For more information, see the Spring Boot SSL documentation.

Configure endpoints

Spring Boot applications typically use the server.port property to configure the port. Use WithHttpEndpoint to expose the endpoint:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp("spring-api", "../spring-app", "../agents/opentelemetry-javaagent.jar")
    .WithHttpEndpoint(port: 8080);

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

Observability

The Java integration uses the OpenTelemetry Java agent to provide observability features. The agent automatically instruments your Java application and exports telemetry to the Aspire dashboard.

Make sure to download the OpenTelemetry Java agent and specify its path when calling AddSpringApp.