# Java integration

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<Image
  src={javaIcon}
  alt="Java logo"
  width={100}
  height={100}
  class:list={'float-inline-left icon'}
  data-zoom-off
/>

This article is the reference for the Aspire Java hosting integration from the [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire). It enumerates the AppHost APIs you use to model Java applications — including Spring Boot apps — in your [`AppHost`](/get-started/app-host/) project.

:::note
TypeScript AppHost support for this integration is not yet available. All AppHost examples on this page are in C#.
:::

## Hosting integration

<InstallPackage packageName="CommunityToolkit.Aspire.Hosting.Java" shortName="java --source CommunityToolkit" />

:::note
This integration requires the OpenTelemetry Java agent for observability support. Download the agent JAR and place it in the `./agents` directory relative to your AppHost project. Download from: [OpenTelemetry Java Agent releases](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases).
:::

### Add Spring Boot app

To add a Spring Boot application to your AppHost, use the `AddSpringApp` extension method:

```csharp title="C# — AppHost.cs"
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>("apiservice")
    .WithReference(javaApp);

builder.Build().Run();
```

The `AddSpringApp` method accepts:
- **name**: The resource name shown 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, host Java applications in containers using `JavaAppContainerResourceOptions`:

```csharp title="C# — AppHost.cs"
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...
builder.Build().Run();
```

### Executable hosting

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

```csharp title="C# — AppHost.cs"
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...
builder.Build().Run();
```

### Configure endpoints

Spring Boot applications use the `server.port` property to configure the port. Use `WithHttpEndpoint` to expose the endpoint to other resources in the AppHost:

```csharp title="C# — AppHost.cs"
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...
builder.Build().Run();
```

### Certificate trust (Linux and macOS)

On Linux and macOS, add the following to your Spring Boot application's `application.properties` to trust the Aspire development certificates:

```properties title="application.properties"
server.ssl.trust-store=/path/to/aspire/dev/certificate.p12
server.ssl.trust-store-password=p@ssw0rd1
```

For more information, see the [Spring Boot SSL documentation](https://docs.spring.io/spring-boot/reference/features/ssl.html).

## Observability

The Java integration uses the OpenTelemetry Java agent to automatically instrument your application and export telemetry to the Aspire dashboard.

Download the OpenTelemetry Java agent and specify its path when calling `AddSpringApp`. For more information, see [OpenTelemetry Java instrumentation](https://opentelemetry.io/docs/languages/java/).

## See also

- [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
- [Spring Boot documentation](https://spring.io/projects/spring-boot)
- [OpenTelemetry Java](https://opentelemetry.io/docs/languages/java/)
- [Aspire integrations overview](/integrations/overview/)