Solr Client

A Solr Client container is an ephemeral container that is used to run Solr commands.

Building a Solr Client image

The Solr Client image for i2 Analyze is built on top of a Solr image maintained by i2 Group on Docker Hub. The Dockerfile is modified to configure Solr for use with i2 Analyze.

Docker build command

The Solr image is built from the Dockerfile in images/solr_client. The following docker build command builds the Solr image:

docker build -t "solr_client_redhat:4.4.4" images/solr_client \
  --build-arg I2ANALYZE_VERSION="4.4.4"

For examples of the build commands, see build-images script.

Running a Solr Client container

A Solr Client container uses the Solr image. In the docker run command, you can use -e to pass environment variables to Solr on the container. The environment variables are described in environment variables

The container will run with a default User ID and Group ID of 8983 and be added to the i2analyze group (GROUP_ID env variable can be used to change i2analyze group ID). All files in mounted directories will be created with these IDs. If files are manipulated externally these IDs must be retained or the container will not function correctly.

For more information about the command, see docker run reference.

Docker run command

The following docker run command runs a Solr Client container:

docker run --rm \
    --net "eia" \
    -v "/home/<user-name>/analyze-deployment-tooling/examples/pre-prod/configuration:/opt/configuration" \
    -e USER_ID="$(id -u)" -e GROUP_ID="$(id -g)" \
    -e SOLR_ADMIN_DIGEST_USERNAME="solr" \
    -e SOLR_ADMIN_DIGEST_PASSWORD="SOLR_ADMIN_DIGEST_PASSWORD" \
    -e ZOO_DIGEST_USERNAME="solr" \
    -e ZOO_DIGEST_PASSWORD="ZOO_DIGEST_PASSWORD" \
    -e ZOO_DIGEST_READONLY_USERNAME="readonly-user" \
    -e ZOO_DIGEST_READONLY_PASSWORD="ZOO_DIGEST_READONLY_PASSWORD" \
    -e SECURITY_JSON="SECURITY_JSON" \
    -e SOLR_ZOO_SSL_CONNECTION=true \
    -e SSL_PRIVATE_KEY="SSL_PRIVATE_KEY" \
    -e SSL_CERTIFICATE="SSL_CERTIFICATE" \
    -e SSL_CA_CERTIFICATE="SSL_CA_CERTIFICATE" \
    "solr_client_redhat:4.4.4" "$@"

The local group ID is required so that the solr user is created in the Docker container with a GROUP_ID that is the same as the local user. The user is required to ensure that the local user can access any files that are generated on the container. The value of $id comes from your shell.

For an example of the docker run command, see run_solr_client_command function in client_functions.sh script. For an example of how to use run_solr_client_command function, see run_solr_client_command.

Bind mounts

Secrets:
A directory that contains all of the secrets that this tool requires. Specifically this includes credentials to access zookeeper and certificates used in SSL.
The directory is mounted to /run/secrets inside the container. This can then be used by other environment variables such as ZOO_DIGEST_USERNAME_FILE to locate the secrets. In a production environment, the orchestration environment can provide the secrets to the file system or the secrets can be passed in via environment variables. The mechanism that is used here simulates the orchestration system providing the secrets as files. This is achieved by using a bind mount. In production this would not be required.

Configuration:
The Solr client requires the i2 Analyze configuration to perform some Solr operations. To access the configuration, the configuration directory must be mounted into the container.

Environment variables

To configure the Solr client, you can provide environment variables to the Docker container in the docker run command.

Environment variable	Description
`SOLR_ADMIN_DIGEST_USERNAME`	For usage see Command Parsing
`SOLR_ADMIN_DIGEST_PASSWORD`	For usage see Command Parsing
`ZOO_DIGEST_USERNAME`	The ZooKeeper administrator user name. This environment variable maps to the `zkDigestUsername` system property.
`ZOO_DIGEST_PASSWORD`	The ZooKeeper administrator password. This environment variable maps to the `zkDigestPassword` system property.
`ZOO_DIGEST_READONLY_USERNAME`	The ZooKeeper read-only user name. This environment variable maps to the `zkDigestReadonlyUsername` system property.
`ZOO_DIGEST_READONLY_PASSWORD`	The ZooKeeper read-only password. This environment variable maps to the `zkDigestReadonlyPassword` system property.
`SECURITY_JSON`	The Solr security.json. Solr Basic Authentication
`SOLR_ZOO_SSL_CONNECTION`	See Secure Environment Variables.
`SERVER_SSL`	See Secure Environment Variables.
`SSL_PRIVATE_KEY`	See Secure Environment Variables.
`SSL_CERTIFICATE`	See Secure Environment Variables.
`SSL_CA_CERTIFICATE`	See Secure Environment Variables.

Command parsing

When commands are passed to the Solr client by using the "$@" notation, the command that is passed to the container must be escaped correctly. On the container, the command is run using docker exec "$@". Because the command is passed to the docker run command using bash -c, the command must be maintained as a double quoted string.

For example:

run_solr_client_command bash -c "curl -u \"\${SOLR_ADMIN_DIGEST_USERNAME}:\${SOLR_ADMIN_DIGEST_PASSWORD}\" 
   --cacert /run/secrets/CA.cer 
   \"${SOLR1_BASE_URL}/solr/main_index/update?commit=true\" 
   -H Content-Type:text/xml --data-binary \"<delete><query>*:*</query></delete>\""

Different parts of the command must be escaped in different ways:

\"\${SOLR_ADMIN_DIGEST_USERNAME}:\${SOLR_ADMIN_DIGEST_PASSWORD}\"
Because the curl command uses the container's local environment variables to obtain the values of SOLR_ADMIN_DIGEST_USERNAME and SOLR_ADMIN_DIGEST_PASSWORD, the $ is escaped by a \.
The " around both of the variables are escaped with a \ to prevent the splitting of the command, which means that the variables are evaluated in the container's environment.
\"${SOLR1_BASE_URL}/solr/main_index/update?commit=true\"
The URL is surrounded in " because the string contains a variable. The " are escaped with a \.
Because the SOLR1_FQDN variable is evaluated before it is passed to the container, the $ is not escaped.
\"<delete><query>*:*</query></delete>\"
The data portion of the curl command is escaped with " because it contains special characters. The " are escaped with a \.