Install the Java agent using a container

This topic provides general guidance for installing the Contrast Java agent in a containerized application, with Docker as an example.

Note

If the agent takes a long time to start, Java Agent Effects on Startup Performance and Java agent with Docker provide details to help you resolve this issue.

Before you begin

You should have a basic understanding of how containers and related software work. You may need to adjust the instructions to meet your specific circumstances.

ECS support

Using this procedure, you can install the Contrast Java agent using a Docker container in an Amazon Elastic Container Service (ECS) environment.

Step 1: Install the agent

Contrast can be added either before or after the application is added to the container image. The recommended approach is with the use of named multi-stage builds. For example:

FROM eclipse-temurin:17

# Hidden for brevity...

# Copy the required agent files from the official Contrast agent image.
COPY --from=contrast/agent-java:latest /contrast/contrast-agent.jar /opt/contrast/contrast.jar

In this example, the latest Java agent is used. Check DockerHub for available tags.

Step 2: Configure the agent

When installing the Java agent into a container:

Use a YAML configuration file for common configuration settings so it can be placed in the base image. For example, a common configuration might include redirecting logging to console output, proxy configuration, or performance tuning.
The Contrast agent configuration editor can help with configuring the agent correctly.
Create and copy the YAML file into the base image, then copy the file into the base image Dockerfile using:
```
COPY WORKSPACE/contrast_security.yaml /opt/contrast/contrast_security.yaml
```

Use Java system properties or environment variables for application-specific configuration values so you can uniquely configure options for each application.

Contrast configuration	Function	Java system property	Environment variable
Application metadata	Specify application-specific metadata Create application metadata before you specify them in the configuration.	`-Dcontrast.application.metadata`	CONTRAST__APPLICATION__METADATA
Application session metadata	Send application details like build number, version, GIT hash, and other session metadata.	`-Dcontrast.application.session_metadata`	CONTRAST__APPLICATION__SESSION_METADATA
Application group	Specify the application access group for this application during onboarding. Create these groups in Contrast first.	`-Dcontrast.application.group`	CONTRAST__APPLICATION__GROUP
Server environment	Specify in which environments the application is running: Development, QA and Production.	`-Dcontrast.server.environment`	CONTRAST__SERVER__ENVIRONMENT

Step 3: Update JVM parameters

To attach any profiler to a Java application, you need to pass a -javaagent flag to the application by setting JAVA_TOOL_OPTIONS environment variables.

Pre-populate the Contrast common JVM parameters in a separate environment variable in the base image, so the application team can use it in JAVA_TOOL_OPTIONS. For example:

For the base image Dockerfile:

ENV CONTRAST_OPTS "-javaagent:/opt/contrast/contrast.jar \
-Dcontrast.config.path=/opt/contrast/contrast_security.yaml"

For the application image Dockerfile:

ENV JAVA_TOOL_OPTIONS $CONTRAST_OPTS \
-Dcontrast.application.metadata=bU=<value>,contactEmail=<value>,contactName=<value> \
-Dcontrast.application.group=APP_GROUP

Step 4: Run the application image

After you add and configure the agent in a base image, run the image.

For the agent to send data to Contrast, it needs agent authentication keys. To protect the agent credentials, you can use the Docker secret and pass them as environment variables during deployment time. Here is an example of the Docker run command:

docker run -e CONTRAST__API__URL=https://app.contrastsecurity.com -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value> -e CONTRAST__API__USER_NAME=<value> -e CONTRAST__SERVER__NAME=<value> -e CONTRAST__SERVER__ENVIRONMENT=<value> image_with_contrast

You can verify that Contrast is running by checking the container log. You should see messages like these:

2020-05-28 22:36:29,910 [main STDOUT] INFO - Copyright: 2019 Contrast Security, Inc
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contact: support@contrastsecurity.com
2020-05-28 22:36:29,910 [main STDOUT] INFO - License: Commercial
2020-05-28 22:36:29,910 [main STDOUT] INFO - NOTICE: This Software and the patented inventions embodied within may only be used as part of
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security's commercial offerings. Even though it is made available through public
2020-05-28 22:36:29,910 [main STDOUT] INFO - repositories, use of this Software is subject to the applicable End User Licensing Agreement
2020-05-28 22:36:29,910 [main STDOUT] INFO - found at https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed between
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security and the End User. The Software may not be reverse engineered, modified,
2020-05-28 22:36:29,910 [main STDOUT] INFO - repackaged, sold, redistributed or otherwise used in a way not consistent with the End User
2020-05-28 22:36:29,910 [main STDOUT] INFO - License Agreement.
[Contrast] Thu May 28 22:36:30 EDT 2020 Effective instructions: Assess=false, Protect=true
[Contrast] Thu May 28 22:36:30 EDT 2020 String Supporter has been disabled
[Contrast] Thu May 28 22:36:30 EDT 2020 Logging security messages to /Users/usernamehere/.contrast/security.log
[Contrast] Thu May 28 22:36:31 EDT 2020 Starting JVM [1862ms]