To get started with infinispan server on your local machine simply execute:

docker run -p 11222:11222 infinispan/server

or

podman run --net=host -p 11222:11222 infinispan/server

By default the image has authentication and enabled on all exposed endpoints. When executing the above command the image automatically generates a username/password combo with the "admin" role, prints the values to stdout and then starts the Infinispan server with the authenticated Hotrod and Rest endpoints exposed on port 11222. Therefore, it's necessary to utilise the printed credentials when attempting to access the exposed endpoints via clients.

It's also possible to provide a admin username/password combination via environment variables like so:

docker run -p 11222:11222 -e USER="admin" -e PASS="changeme" infinispan/server

HotRod Clients

When connecting a HotRod client to the image, the following SASL properties must be configured on your client (with the username and password properties changed as required):

infinispan.client.hotrod.auth_username=admin
infinispan.client.hotrod.auth_password=changme
infinispan.client.hotrod.sasl_mechanism=DIGEST-MD5

Identities Batch

User identities and roles can be defined by providing a cli batch file via the IDENTITIES_BATCH env variable. All of the cli commands defined in this file are executed before the server is started, therefore it's only possible to execute offline commands otherwise the container will fail. For example, including create cache ... in the batch would fail as it requires a connection to an Infinispan server.

Infinispan provides implicit roles for some users.

[TIP] Check Infinispan documentation⁠ to know more about implicit roles and authorization

Below is an example Identities batch CLI file identities.batch, that defines four users and their role:

user create "Alan Shearer" -p "striker9" -g admin
user create "observer" -p "secret1" 
user create "deployer" -p "secret2" 
user create "Rigoberta Baldini" -p "secret3" -g monitor

To run the image using a local identities.batch, execute:

docker run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 infinispan/server

Server Configuration

The Infinispan image passes all container arguments to the created server, therefore it's possible to configure the server in the same manner as a non-containerised deployment.

Below shows how a docker volume⁠ can be created and mounted in order to run the Infinispan image with the local configuration file my-infinispan-config.xml located in the users current working directory.

docker run -v $(pwd):/user-config -e IDENTITIES_BATCH="/user-config/identities.batch" -p 11222:11222 infinispan/server -c /user-config/my-infinispan-config.xml

Kubernetes/Openshift Clustering

When running in a managed environment such as Kubernetes, it is not possible to utilise multicasting for initial node discovery, thefore we must utilise the JGroups DNS_PING⁠ protocol to discover cluster members. To enable this, we must provide the jgroups.dnsPing.query property and configure the kubernetes stack.

To utilise the tcp stack with DNS_PING, execute the following config:

docker run -v $(pwd):/user-config infinispan/server --bind-address=0.0.0.0  -Dinfinispan.cluster.stack=kubernetes -Djgroups.dns.query="infinispan-dns-ping.myproject.svc.cluster.local"

Java Properties

It's possible to provide additional java properties and JVM options to the server images via the JAVA_OPTIONS env variable. For example, to quickly configure CORS without providing a server.yaml file, it's possible to do the following:

docker run -e JAVA_OPTIONS="-Dinfinispan.cors.enableAll=https://host.domain:port" infinispan/server

Deploying artifacts to the server lib directory

Deploy artifacts to the server lib directory using the SERVER_LIBS env variable. For example, to add the PostgreSQL JDBC driver to the server:

docker run -e SERVER_LIBS="org.postgresql:postgresql:42.3.1" infinispan/server

The SERVER_LIBS variable supports multiple, space-separated artifacts represented as URLs or as Maven coordinates. Archive artifacts in .tar, .tar.gz or .zip formats will be extracted. Refer to the CLI⁠install command help to learn about all possible arguments and options.

Debugging

Image Configuration

The image scripts that are used to configure and launch the executables can be debugged by setting the environment variable DEBUG=TRUE as follows:

 docker run -e DEBUG=true infinispan/<image-name>

Infinispan Server

It's also possible to debug the Infinispan server in the image by setting the DEBUG_PORT environment variable as follows:

docker run -e DEBUG_PORT="*:8787" -p 8787:8787 infinispan/server

Image Tools

In order to keep the image's size as small as possible, we utilise the ubi-minimal⁠ image. Consequently, the image does not provide all of the tools that are commonly available in linux distributions. Below is a list of common tools/recipes that are useful for debugging.

Kubernetes

Liveness and Readiness Probes

It's recommended to utilise Infinispan's REST endpoint in order to determine if the server is ready/live. To do this, you can utilise the Kubernetes httpGet probes⁠ as follows:

livenessProbe:
httpGet:
  path: /rest/v2/cache-managers/default/health/status
  port: 11222
failureThreshold: 5
initialDelaySeconds: 10
successThreshold: 1
timeoutSeconds: 10
readinessProbe:
httpGet:
  path: /rest/v2/cache-managers/default/health/status
  port: 11222
failureThreshold: 5
initialDelaySeconds: 10
successThreshold: 1
timeoutSeconds: 10