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"
   EnvVar: SOLR_DOCKER_BASE_IMAGE
   Gradle Property: -Psolr.docker.baseImage

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, e.g. "9.0.0-SNAPSHOT"
   EnvVar: SOLR_DOCKER_IMAGE_TAG
   Gradle Property: -Psolr.docker.imageTag

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} (both 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 Image
-------

The Official Solr Docker Image is also generated within this module.
This section should only be used by developers testing that their changes to the Solr project are compatible with the Official image.
All users should build custom images using the instructions above.

NOTE: All gradle commands for the Official Dockerfile 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 an official Solr Dockerfile.
The Dockerfile will be created at: solr/docker/build/Dockerfile.official

gradlew createDockerfileOfficial

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

gradlew testBuildDockerfileOfficial

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

gradlew testDockerfileOfficial