# Dev Services for Infinispan

Quarkus supports a feature called Dev Services that allows you to create various datasources without any config. If you have docker running and have not configured `quarkus.infinispan-client.hosts`, Quarkus will automatically start an Infinispan container when running tests or dev mode, and automatically configure the connection.

When running the production version of the application, the Infinispan connection need to be configured as normal, so if you want to include a production database config in your `application.properties` and continue to use Dev Services we recommend that you use the `%prod.` profile to define your Infinispan settings.

Dev Services for Infinispan relies on Docker/Podman to start the server.

## Connecting to the running Infinispan Server

You don’t need to configure anything in dev mode. The server will be running in a random port. If you need a fixed port, then configure `quarkus.infinispan-client.devservices.port` property.

| The running Infinispan Server has authentication enabled and a user with full admin role. The credentials of the user are admin/password.

### Accessing to the Infinispan Server Console

Infinispan Server provides a web console that can be accessed with a browser:

1. Open the Dev UI

2. You will see an Infinispan Client box. Click on Web Console and enter the credentials above.

If your environment does not support Docker, you will need to spin up an Infinispan Server manually, or connect to an already running server.

## Overriding the Infinispan Server Image

The extension is updated regularly and the Dev Services will start the latest final version image of Infinispan. Use `quarkus.infinispan-client.devservices.image-name` property to specify another image that fits your needs.

## Enabling / Disabling Dev Services for Infinispan

Dev Services for Infinispan is automatically enabled unless:

- `quarkus.infinispan-client.devservices.enabled` is set to `false`

- the `quarkus.infinispan-client.hosts` is configured

Dev Services for Infinispan relies on Docker to start the broker. If your environment does not support Docker, you will need to start the broker manually, or connect to an already running broker. You can configure the broker address using `quarkus.infinispan-client.hosts`.

## Providing configuration to the running server

Dev Services for Infinispan will spin up an Infinispan with the infinispan.xml file by default. However, there are cases where is helpful to provide some extra configuration to the server. This can be done by adding configuration files in xml, yaml or json to the resources classpath and providing the following configuration:

    quarkus.infinispan-client.devservices.config-files=server-config-override.xml (1)

1 | server-config-override.xml is a file under the resources folder

    <infinispan> (1)
        <cache-container>
            <local-cache name="my-local-cache"> (2)
                <encoding media-type="application/x-protostream" />
            </local-cache>
        </cache-container>
    </infinispan>

1 | The content of server-config-override.xml file
2 | By providing a cache configuration, this cache will be present on the server container

## Cross Site Replication

If you want run the Infinispan Server container with Cross Site Replication configuration, you need to provide a site name.

    quarkus.infinispan-client.devservices.site=NYC (1)
    quarkus.infinispan-client.devservices.mcast-port=46666 (2)

1 | Provides a site name for your Infinispan cluster
2 | Eventually configure a mcastPort if you want to avoid creating a cluster with another container

| Learn more about Cross Site Replication in the Infinispan Cross Site Replication documentation guide and in the Infinispan Cross Site Replication simple code tutorial.

## Multiple Dev Services for named connections

The Infinispan Client extension supports connecting to more than one Infinispan Cluster with the named connections. If you need to spin an additional Dev Service for a connection name, configure at least on property in the application properties:

    quarkus.infinispan-client.conn-2.devservices.enabled=true

## Tracing with OpenTelemetry

Infinispan supports server tracing using OpenTelemetry. Starting from Infinispan 15.0, you need to configure tracing in the server’s settings. To enable tracing in Dev Services, you need to add extra settings using the `quarkus.infinispan-client.devservices.config-files` property.

    infinispan:
            cacheContainer:
                    tracing:
                            collector-endpoint: "http://jaeger:4318" (1)
                            enabled: true (2)
                            exporter-protocol: "OTLP" (3)
                            service-name: "infinispan-server" (4)
                            security: false (5)

1 | Collector endpoint. Assuming a container service name 'jaeger' is running.
2 | Enables tracing.
3 | Exporter protocol. OLTP is the OpenTelemetry protocol.
4 | The service name that will be registered in the tracing collector, Jaeger in this case.
5 | Enables 'security' category tracing.

See below the equivalent in XML and JSON.

    <infinispan>
      <cache-container statistics="true">
        <tracing collector-endpoint="http://jaeger:4318"
                 enabled="true"
                 exporter-protocol="OTLP"
                 service-name="infinispan-server"
                 security="false" />
      </cache-container>
    </infinispan>

    {
      "infinispan" : {
        "cache-container" : {
          "statistics" : true,
          "tracing" : {
            "collector-endpoint" : "http://jaeger:4318",
            "enabled" : true,
            "exporter-protocol" : "OTLP",
            "service-name" : "infinispan-server",
            "security" : false
          }
        }
      }
    }

You need to name the Jaeger service or get the IP running the following command to configure the exporter endpoint.

    docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' jaeger

## Persistence layer for Infinispan

Infinispan caches provide several features that need to connect to a persistence layer using a particular SQL database driver such as persisting caches in a SQL database or off-loading database tables or queries with SQL cache stores.

Infinispan needs the SQL Java Driver depending on the database kind the application is using. To spin up a container with a particular SQL driver, configure `quarkus.infinispan-client.devservices.artifacts`.

| Learn more about persistence and SQL Cache Stores check the SQL Store Demo + Quarkus Demo and the Infinispan Persistence Documentation guide.

## Shared server

Most of the time you need to share the server between applications. Dev Services for Infinispan implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.

| Dev Services for Infinispan starts the container with the `infinispan` label which is used to identify the container.

If you need multiple (shared) servers, you can configure the `quarkus.infinispan-client.devservices.service-name` attribute and indicate the server name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is `infinispan`.

Sharing is enabled by default in dev mode, but disabled in test mode. You can disable the sharing with `quarkus.infinispan-client.devservices.shared=false`

## Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.infinispan-client.devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_ENABLED` | boolean | `true`
`quarkus.infinispan-client.devservices.create-default-client` When the configuration is empty, an Infinispan default client is automatically created to connect to the running dev service. However, there are scenarios where creating this client is unnecessary, yet we still need to spin up an Infinispan Server. In such cases, this property serves to determine whether the client should be created by default or not by the extension. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_CREATE_DEFAULT_CLIENT` | boolean | `true`
`quarkus.infinispan-client.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_PORT` | int |
`quarkus.infinispan-client.devservices.shared` Indicates if the Infinispan server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Infinispan starts a new container. The discovery uses the `quarkus-dev-service-infinispan` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_SHARED` | boolean | `true`
`quarkus.infinispan-client.devservices.service-name` The value of the `quarkus-dev-service-infinispan` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Infinispan looks for a container with the `quarkus-dev-service-infinispan` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-infinispan` label set to the specified value. This property is used when you need multiple shared Infinispan servers. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_SERVICE_NAME` | string | `infinispan`
`quarkus.infinispan-client.devservices.image-name` The image to use. Note that only official Infinispan images are supported. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_IMAGE_NAME` | string |
`quarkus.infinispan-client.devservices.artifacts` List of the artifacts to automatically download and add to the Infinispan server libraries. For example a Maven coordinate (org.postgresql:postgresql:42.3.1) or a dependency location url. If an invalid value is passed, the Infinispan server will throw an error when trying to start. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_ARTIFACTS` | list of string |
`quarkus.infinispan-client.devservices.site` Add a site name to start the Infinispan Server Container with Cross Site Replication enabled (ex. lon). Cross Site Replication is the capability to connect two separate Infinispan Server Clusters that might run in different Data Centers, and configure backup caches to copy the data across the clusters with active-active or active-passive replication. See more about Cross Site Replication in the Infinispan Documentation https://infinispan.org/docs/stable/titles/xsite/xsite.html Configure `mcast-port` to avoid forming a cluster with any other running Infinispan Server container. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_SITE` | string |
`quarkus.infinispan-client.devservices.mcast-port` If you are running an Infinispan Server already in docker, if the containers use the same mcastPort they will form a cluster. Set a different mcastPort to create a separate cluster in Docker (e. 46656). A common use case in a local Docker development mode, is the need of having two different Infinispan Clusters with Cross Site Replication enabled. see https://github.com/infinispan/infinispan-simple-tutorials/blob/main/infinispan-remote/cross-site-replication/docker-compose/ Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_MCAST_PORT` | int |
`quarkus.infinispan-client.devservices.container-env."environment-variable-name"` Environment variables that are passed to the container. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_` | Map<String,String> |
`quarkus.infinispan-client.devservices.config-files` Infinispan Server configuration chunks to be passed to the container. Environment variable: `QUARKUS_INFINISPAN_CLIENT_DEVSERVICES_CONFIG_FILES` | list of string |