Elasticsearch Dev Service

A service providing an Elasticsearch search and analytics engine for development and testing purposes.

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

Spring AI (Vector Store)
Spring Data Elasticsearch

Dependencies

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

Gradle
Maven

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

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-elasticsearch</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 and run the application in dev mode, Arconia keeps 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. Changes to the configuration of a Dev Service take effect once you stop and start the application again.

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, each application starts its own Elasticsearch Dev Service. To let multiple applications running simultaneously in dev mode use the same one, set the arconia.dev.services.elasticsearch.reuse-strategy property to framework: the application connects to a running Elasticsearch Dev Service started by another application if available, or else starts its own that other applications can discover in turn. The applications using the same Dev Service must use the same password. Learn more about Reusing Dev Services.

Configuring the Dev Service

You can configure the Dev Service via configuration properties.

Property Default Description

Property	Default	Description
`arconia.dev.services.elasticsearch.enabled`	`true`	Whether the dev service is enabled.
`arconia.dev.services.elasticsearch.image-name`	`docker.elastic.co/elasticsearch/elasticsearch`	Full name of the container image used in the dev service.
`arconia.dev.services.elasticsearch.environment`	`{}`	Environment variables to set in the service.
`arconia.dev.services.elasticsearch.network-aliases`	`[]`	Additional hostnames the dev service container is reachable by on the shared network, next to the name of the dev service. Only applicable when the shared network is enabled.
`arconia.dev.services.elasticsearch.port`	`0`	Fixed port for exposing the Elasticsearch database port to the host. When it’s 0 (default), a random available port is assigned dynamically.
`arconia.dev.services.elasticsearch.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.elasticsearch.reuse-strategy`	`none`	Strategy for reusing a running container for the dev service instead of starting a new one. With `framework`, the dev service is discoverable by other applications, and the application connects to an existing dev service if available. With `testcontainers`, the container is kept running across application restarts, relying on the Testcontainers reusable containers feature, which must be enabled in the `~/.testcontainers.properties` file; such containers are not stopped automatically and must be cleaned up manually. Only applicable in dev mode.
`arconia.dev.services.elasticsearch.startup-timeout`	`30s`	Maximum waiting time for the service to start, counted from the container start.
`arconia.dev.services.elasticsearch.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.elasticsearch.ssl.enabled`	`false`	Whether to enable SSL support for the dev service.
`arconia.dev.services.elasticsearch.ssl.pem.keystore.certificate`		Location or content of the certificate or certificate chain in PEM format.
`arconia.dev.services.elasticsearch.ssl.pem.keystore.private-key`		Location or content of the private key in PEM format.
`arconia.dev.services.elasticsearch.ssl.pem.keystore.private-key-password`		Password used to decrypt an encrypted private key.
`arconia.dev.services.elasticsearch.ssl.pem.key.alias`		The alias that identifies the key in the key store.
`arconia.dev.services.elasticsearch.ssl.pem.key.password`		The password used to access the key in the key store.
`arconia.dev.services.elasticsearch.ssl.pem.protocol`	`TLS`	SSL Protocol to use.
`arconia.dev.services.elasticsearch.ssl.pem.options.ciphers`		Supported SSL ciphers.
`arconia.dev.services.elasticsearch.ssl.pem.options.enabled-protocols`		Enabled SSL protocols.
`arconia.dev.services.elasticsearch.ssl.jks.keystore.location`		Location of the resource containing the store content.
`arconia.dev.services.elasticsearch.ssl.jks.keystore.password`		Password used to access the store.
`arconia.dev.services.elasticsearch.ssl.jks.keystore.type`		Type of the store to create, e.g. JKS.
`arconia.dev.services.elasticsearch.ssl.jks.keystore.provider`		Provider for the store.
`arconia.dev.services.elasticsearch.ssl.jks.key.alias`		The alias that identifies the key in the key store.
`arconia.dev.services.elasticsearch.ssl.jks.key.password`		The password used to access the key in the key store.
`arconia.dev.services.elasticsearch.ssl.jks.protocol`	`TLS`	SSL Protocol to use.
`arconia.dev.services.elasticsearch.ssl.jks.options.ciphers`		Supported SSL ciphers.
`arconia.dev.services.elasticsearch.ssl.jks.options.enabled-protocols`		Enabled SSL protocols.

arconia.dev.services.elasticsearch.enabled

true

Whether the dev service is enabled.

arconia.dev.services.elasticsearch.image-name

docker.elastic.co/elasticsearch/elasticsearch

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

arconia.dev.services.elasticsearch.environment

{}

Environment variables to set in the service.

arconia.dev.services.elasticsearch.network-aliases

[]

Additional hostnames the dev service container is reachable by on the shared network, next to the name of the dev service. Only applicable when the shared network is enabled.

arconia.dev.services.elasticsearch.port

0

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

arconia.dev.services.elasticsearch.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.elasticsearch.reuse-strategy

none

Strategy for reusing a running container for the dev service instead of starting a new one. With framework, the dev service is discoverable by other applications, and the application connects to an existing dev service if available. With testcontainers, the container is kept running across application restarts, relying on the Testcontainers reusable containers feature, which must be enabled in the ~/.testcontainers.properties file; such containers are not stopped automatically and must be cleaned up manually. Only applicable in dev mode.

arconia.dev.services.elasticsearch.startup-timeout

30s

Maximum waiting time for the service to start, counted from the container start.

arconia.dev.services.elasticsearch.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.elasticsearch.ssl.enabled

false

Whether to enable SSL support for the dev service.

arconia.dev.services.elasticsearch.ssl.pem.keystore.certificate

Location or content of the certificate or certificate chain in PEM format.

arconia.dev.services.elasticsearch.ssl.pem.keystore.private-key

Location or content of the private key in PEM format.

arconia.dev.services.elasticsearch.ssl.pem.keystore.private-key-password

Password used to decrypt an encrypted private key.

arconia.dev.services.elasticsearch.ssl.pem.key.alias

The alias that identifies the key in the key store.

arconia.dev.services.elasticsearch.ssl.pem.key.password

The password used to access the key in the key store.

arconia.dev.services.elasticsearch.ssl.pem.protocol

TLS

SSL Protocol to use.

arconia.dev.services.elasticsearch.ssl.pem.options.ciphers

Supported SSL ciphers.

arconia.dev.services.elasticsearch.ssl.pem.options.enabled-protocols

Enabled SSL protocols.

arconia.dev.services.elasticsearch.ssl.jks.keystore.location

Location of the resource containing the store content.

arconia.dev.services.elasticsearch.ssl.jks.keystore.password

Password used to access the store.

arconia.dev.services.elasticsearch.ssl.jks.keystore.type

Type of the store to create, e.g. JKS.

arconia.dev.services.elasticsearch.ssl.jks.keystore.provider

Provider for the store.

arconia.dev.services.elasticsearch.ssl.jks.key.alias

The alias that identifies the key in the key store.

arconia.dev.services.elasticsearch.ssl.jks.key.password

The password used to access the key in the key store.

arconia.dev.services.elasticsearch.ssl.jks.protocol

TLS

SSL Protocol to use.

arconia.dev.services.elasticsearch.ssl.jks.options.ciphers

Supported SSL ciphers.

arconia.dev.services.elasticsearch.ssl.jks.options.enabled-protocols

Enabled SSL protocols.

Using SSL

Elasticsearch only accepts HTTPS connections in its default configuration: it generates a certificate of its own at startup and serves HTTPS with it. Since the application has no way to trust that certificate, the Dev Service serves plain HTTP by default, and the application connects to it with the elastic user and the password Testcontainers sets.

To connect over HTTPS instead, as an application configured for a real Elasticsearch cluster does, set the arconia.dev.services.elasticsearch.ssl.enabled property to true. With no certificate configured, Elasticsearch keeps the one it generates (the protocol and options of the ssl properties don’t apply to it), and the application trusts it through the Spring Boot service connection, which extracts the certificate authority from the container, as described in Spring Boot’s documentation. An application connecting to a container started by another application (see Reusing Dev Services) reads the certificate authority from that container the same way.

arconia:
  dev:
    services:
      elasticsearch:
        ssl:
          enabled: true

To have Elasticsearch serve HTTPS with a certificate of yours instead, configure the certificate and private key it presents.

The Dev Service can serve SSL, so that an application connecting to the real service over SSL does the same in dev and test, and its SSL support is developed and tested against the Dev Service. Set the arconia.dev.services.elasticsearch.ssl.enabled property to true and configure the certificate and private key the Dev Service presents, in PEM form or in a Java keystore, with the same properties as a Spring Boot SSL bundle:

arconia:
  dev:
    services:
      elasticsearch:
        ssl:
          enabled: true
          pem:
            keystore:
              certificate: "classpath:certs/elasticsearch.crt"
              private-key: "classpath:certs/elasticsearch.key"

The container is configured to serve SSL with that certificate, and the application is configured to trust it through the Spring Boot service connection, so no client configuration is needed. The certificate must be valid for the host the application connects to, such as localhost. The ssl.pem and ssl.jks properties take the keystore, key, options, and protocol keys of a spring.ssl.bundle definition. Learn more about SSL with Dev Services, including the certificate requirements.

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.