solr/docker/gradle-help.txt

Docker Images for Solr
======================

In order to build and tag a Solr docker image, merely run the following command:

gradlew docker

This calls the dockerBuild and dockerTag tasks, which have inputs that are described below.

Building
--------

In order to build the Solr Docker image, run:

gradlew dockerBuild

The docker build task accepts the following inputs, all accepted via both Environment Variables and Gradle Properties.

Base Docker Image: (The docker image used for the "FROM" in the Solr Dockerfile)
   Default: "eclipse-temurin:17-jre-jammy"
   EnvVar: SOLR_DOCKER_BASE_IMAGE
   Gradle Property: -Psolr.docker.baseImage

Solr Distribution: (Either Full or Slim, the solr binary distribution to build the docker image with)
   Default: "full"
   EnvVar: SOLR_DOCKER_DIST
   Gradle Property: -Psolr.docker.dist

Tagging and Pushing
-------

To tag the docker image, run the following command.
This will also ensure that the docker image has been built as per the inputs detailed above.

gradlew dockerTag

And to push the image with the given tag, run the following command.
Gradle will ensure that the docker image is built and tagged as the inputs describe before being pushed.

gradlew dockerPush

The docker image tag can be customized via the following options, all accepted via both Environment Variables and Gradle Properties.

Docker Image Repository:
   Default: "apache/solr"
   EnvVar: SOLR_DOCKER_IMAGE_REPO
   Gradle Property: -Psolr.docker.imageRepo

Docker Image Tag:
   Default: the Solr version and distribution (if applicable), e.g. "9.0.0-SNAPSHOT" or "9.5.0-SNAPSHOT-slim"
   EnvVar: SOLR_DOCKER_IMAGE_TAG
   Gradle Property: -Psolr.docker.imageTag

Docker Image Tag Suffix:
   Default: None. Example: "-java21"
   EnvVar: SOLR_DOCKER_IMAGE_TAG_SUFFIX
   Gradle Property: -Psolr.docker.imageTagSuffix

Docker Image Name: (Use this to explicitly set a whole image name. If given, the image repo and image version options above are ignored.)
   Default: {image_repo}/{image_tag}{image_tag_suffix} (all options provided above, with defaults)
   EnvVar: SOLR_DOCKER_IMAGE_NAME
   Gradle Property: -Psolr.docker.imageName

Testing
-------

To test the docker image, run the following command.
This will also ensure that the docker image has been built as per the inputs detailed above in the "Building" section.

gradlew testDocker

If a docker image build parameters were used during building, then the same inputs must be used while testing.
Otherwise a new docker image will be built for the tests to run with.

You can also specify an explicit list of tests to run, or an explicit list of tests to ignore.
Both inputs are optional, and by default all tests will be run.
Each input tasks a comma separated list of test names.

Run specific tests:
   EnvVar: SOLR_DOCKER_TESTS_INCLUDE
   Gradle Property: -Psolr.docker.tests.include

Exclude specific tests:
   EnvVar: SOLR_DOCKER_TESTS_EXCLUDE
   Gradle Property: -Psolr.docker.tests.exclude

The docker tests can also be run concurrently, if explicitly specified.
The parallelization is set by the number of gradle workers you have defined, this cannot be specified separately.
It is recommended to use at most 3 gradle workers when running the Docker tests concurrently.

Run tests in parallel:
   EnvVar: SOLR_DOCKER_TESTS_CONCURRENT=true
   Gradle Property: -Psolr.docker.tests.concurrent=true

-------
The Official Solr Images
-------

The Official Solr Docker Images are also generated within this module.
One Dockerfile/Docker image is created for each Solr binary package, "full" and "slim".
This section should only be used by developers testing that their changes to the Solr project are compatible with the Official images.
All users should build custom images using the instructions above.

NOTE: All gradle commands for the Official Dockerfiles below require the Solr artifacts to be signed with a GPG Key.
For necessary inputs and properties, please refer to:

gradlew helpPublishing

You can use the following command to build both official Solr Dockerfiles.
The Dockerfiles will be created at:
- solr/docker/build/Dockerfile.official-full
- solr/docker/build/Dockerfile.official-slim

gradlew createDockerfileOfficial

You can also test building the official docker images using the following command.
This will build the official Dockerfiles, create a local server to host the local Solr artifacts, and build the Official Solr images using this local server.

gradlew testBuildDockerfileOfficial

You can also run the official Docker images built by the command above through all Solr Docker tests with the following:

gradlew testDockerfileOfficial

In order to build/test just one of the "full" or "slim" images/Dockerfiles, just append "Full" or "Slim" to any of the *DockerfileOfficial tasks above.