Ollama Dev Service

A service providing an Ollama model inference service for development and testing purposes.

It works with Spring Boot libraries that support Ollama, including:

Spring AI (Ollama, OpenAI)

If a native Ollama connection is detected, for example, if you’re already running the Ollama application on your laptop, the Ollama Dev Service will not start a container and the native service will be used instead. The detection targets the URL configured via spring.ai.ollama.base-url, or http://localhost:11434 if not set. You can force the use of the container via the arconia.dev.services.ollama.ignore-native-service property.

Dependencies

First, you need to add the Dev Service dependency to your project.

Gradle
Maven

dependencies {
  testAndDevelopmentOnly "io.arconia:arconia-dev-services-ollama"
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-ollama</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

You can optionally include the Spring Boot DevTools dependency to enable live reload of your application during development.

Gradle
Maven

dependencies {
  developmentOnly "org.springframework.boot:spring-boot-devtools"
}

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

When you use the Spring Boot DevTools in your project, Arconia will keep the Dev Services running while you make changes to your code instead of restarting them with the application. This allows you to see the changes in real-time without having to restart the Dev Services.

Running the Application

When using the Arconia Dev Services, you can keep running your application as you normally would. The Dev Services will automatically start when you run your application.

Gradle
Maven
CLI

./gradlew bootRun

./mvnw spring-boot:run

arconia dev

Unlike the lower-level Testcontainers support in Spring Boot, Arconia doesn’t require special tasks to run your application when using Dev Services (./gradlew bootTestRun or ./mvnw spring-boot:test-run) nor requires you to define a separate @SpringBootApplication class for configuring Testcontainers.

Your integration tests based on @SpringBootTest will automatically use the Dev Services without any additional configuration.

Test slices (e.g. @DataJdbcTest) load only a subset of the auto-configurations, so they don’t pick up Dev Services automatically. You can import the Dev Service explicitly. For example, for the PostgreSQL Dev Service:

@DataJdbcTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
@Import(PostgresqlDevServicesAutoConfiguration.class)
class CustomerRepositoryTests {
    ...
}

By default, when running the application in dev mode, the Dev Service is shared across multiple applications running simultaneously: the application connects to a running Ollama Dev Service started by another application if available, or else starts its own that other applications can discover in turn. Sharing requires the Spring AI Ollama module on the classpath: applications using only the OpenAI-compatible integration always start a dedicated container.

Configuring the Dev Service

You can configure the Dev Service via configuration properties.

Property Default Description

Property	Default	Description
`arconia.dev.services.ollama.enabled`	`true`	Whether the dev service is enabled.
`arconia.dev.services.ollama.image-name`	`ollama/ollama`	Full name of the container image used in the dev service.
`arconia.dev.services.ollama.environment`	`{}`	Environment variables to set in the service.
`arconia.dev.services.ollama.network-aliases`	`[]`	Network aliases to assign to the dev service container.
`arconia.dev.services.ollama.port`	`0`	Fixed port for exposing the Ollama inference service port to the host. When it’s 0 (default), a random available port is assigned dynamically.
`arconia.dev.services.ollama.resources`	`[]`	Resources from the classpath or host filesystem to copy into the container. They can be files or directories that will be copied to the specified destination path inside the container at startup and are immutable (read-only).
`arconia.dev.services.ollama.reuse`	`false`	Whether the container used in the dev service is reused across multiple applications and application restarts, relying on the Testcontainers reusable containers feature. Only applicable in dev mode.
`arconia.dev.services.ollama.shared`	`true`	Whether the dev service is shared among applications running simultaneously. A shared dev service is discoverable by other applications, and the application connects to an existing shared dev service if available instead of starting a new one. Only applicable in dev mode.
`arconia.dev.services.ollama.startup-timeout`	`120s`	Maximum waiting time for the service to start.
`arconia.dev.services.ollama.volumes`	`[]`	Files or directories to mount from the host filesystem into the container. They are mounted at the specified destination path inside the container at startup and are mutable (read-write). Changes in either the host or the container will be immediately reflected in the other.
`arconia.dev.services.ollama.ignore-native-service`	`false`	Whether to ignore an Ollama native service available on the host, but always use the container instead.

arconia.dev.services.ollama.enabled

true

Whether the dev service is enabled.

arconia.dev.services.ollama.image-name

ollama/ollama

Full name of the container image used in the dev service.

arconia.dev.services.ollama.environment

{}

Environment variables to set in the service.

arconia.dev.services.ollama.network-aliases

[]

Network aliases to assign to the dev service container.

arconia.dev.services.ollama.port

0

Fixed port for exposing the Ollama inference service port to the host. When it’s 0 (default), a random available port is assigned dynamically.

arconia.dev.services.ollama.resources

[]

Resources from the classpath or host filesystem to copy into the container. They can be files or directories that will be copied to the specified destination path inside the container at startup and are immutable (read-only).

arconia.dev.services.ollama.reuse

false

Whether the container used in the dev service is reused across multiple applications and application restarts, relying on the Testcontainers reusable containers feature. Only applicable in dev mode.

arconia.dev.services.ollama.shared

true

Whether the dev service is shared among applications running simultaneously. A shared dev service is discoverable by other applications, and the application connects to an existing shared dev service if available instead of starting a new one. Only applicable in dev mode.

arconia.dev.services.ollama.startup-timeout

120s

Maximum waiting time for the service to start.

arconia.dev.services.ollama.volumes

[]

Files or directories to mount from the host filesystem into the container. They are mounted at the specified destination path inside the container at startup and are mutable (read-write). Changes in either the host or the container will be immediately reflected in the other.

arconia.dev.services.ollama.ignore-native-service

false

Whether to ignore an Ollama native service available on the host, but always use the container instead.

You can enable/disable the Dev Service selectively for a specific application mode (development, test), relying on one of the profiles which are automatically configured by Arconia (see Profiles).

You can enable/disable the Dev Service for a specific test class by using the @TestPropertySource annotation or equivalent Spring testing utilities.

Spring AI OpenAI Compatibility

When the Spring AI OpenAI module is on the classpath, the Ollama Dev Service automatically configures the OpenAI client to use the Ollama-compatible API endpoint. The spring.ai.openai.base-url and spring.ai.openai.api-key properties are set dynamically, pointing to the Ollama container when available or to the native Ollama service otherwise.

While the Ollama Dev Service is enabled, these properties take precedence over any user-defined configuration, and the API key is set to ollama. If you want your application to use a real OpenAI endpoint in dev or test mode, disable the Ollama Dev Service via arconia.dev.services.ollama.enabled=false.