Skip to content

Fix Java/Spring hosting integration docs - add missing workingDirectory parameter and Linux/macOS certificate trust information #3710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Fix Java/Spring hosting integration docs - add missing workingDirectory parameter and Linux/macOS certificate trust information #3710

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5d9dea0
Initial plan for issue
Copilot Jun 5, 2025
55adf89
Fix Java hosting integration docs - add missing workingDirectory para…
Copilot Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 36 additions & 6 deletions docs/community-toolkit/hosting-java.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Java/Spring hosting
author: justinyoo
description: A .NET Aspire hosting integration for hosting Java/Spring applications using either the Java runtime or a container.
ms.date: 10/11/2024
ms.date: 01/31/2025
---

# .NET Aspire Java/Spring hosting integration
Expand Down Expand Up @@ -38,9 +38,30 @@ Invoke-WebRequest `

---

## Platform-specific considerations

### Linux and macOS certificate trust

On Linux and macOS platforms, you might need to import the .NET Aspire OpenTelemetry certificate into the Java certificate store for telemetry to work properly. Without this step, your Java application will start successfully, but telemetry collection might fail with certificate errors.

To add the certificate to the Java truststore, you can use the following steps:

1. Export the .NET Aspire dashboard certificate (this varies by your setup)
1. Import it into the Java truststore using the `keytool` command:

```bash
keytool -import -trustcacerts -alias aspire-dashboard \
-file aspire-dashboard.crt \
-keystore $JAVA_HOME/lib/security/cacerts \
-storepass changeit
```

> [!NOTE]
> The exact steps for obtaining and importing the certificate may vary depending on your development environment and .NET Aspire configuration.

## Get started

To get started with the .NET Aspire Azure Static Web Apps emulator integration, install the [📦 CommunityToolkit.Aspire.Hosting.Java](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java) NuGet package in the AppHost project.
To get started with the .NET Aspire Java/Spring hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.Java](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java) NuGet package in the AppHost project.

### [.NET CLI](#tab/dotnet-cli)

Expand All @@ -65,32 +86,41 @@ The following sections detail various example usage scenarios, from hosting a co

### [Container hosting](#tab/container-hosting)

In the _:::no-loc text="Program.cs":::_file of your app host project, call the `AddSpringApp` method to define the containerized Spring app. Use the `JavaAppContainerResourceOptions` to define the containerized Spring app.
In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddSpringApp` method to define the containerized Spring app. The `JavaAppContainerResourceOptions` allows you to specify the container image and OpenTelemetry agent configuration.

```csharp
var containerapp = builder.AddSpringApp(
"containerapp",
new JavaAppContainerResourceOptions
{
ContainerImageName = "<repository>/<image>",
OtelAgentPath = "<agent-path>"
ContainerImageName = "your-registry/your-spring-app:latest",
OtelAgentPath = "/agents"
});
```

The `ContainerImageName` should point to your Spring Boot application's container image, and `OtelAgentPath` specifies the path within the container where the OpenTelemetry Java agent is located.

### [Executable hosting](#tab/executable-hosting)

In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddSpringApp` method to define the executable Spring app. Use the `JavaAppExecutableResourceOptions` to define the executable Spring app.
In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddSpringApp` method to define the executable Spring app. The `workingDirectory` parameter specifies the directory containing your Java application, and the `JavaAppExecutableResourceOptions` defines the executable Spring app configuration.

```csharp
var executableapp = builder.AddSpringApp(
"executableapp",
workingDirectory: "../path/to/java/app",
new JavaAppExecutableResourceOptions
{
ApplicationName = "target/app.jar",
OtelAgentPath = "../../../agents"
});
```

The parameters are defined as follows:

- `workingDirectory`: **(Required)** The directory containing your Java/Spring application. This should be the root directory of your Java project.
- `ApplicationName`: The path to your JAR file relative to the working directory (typically `target/your-app.jar` for Maven projects).
- `OtelAgentPath`: The path to the OpenTelemetry Java agent JAR file relative to the working directory.

---

## See also
Expand Down