Install the Java agent using a container

Before you begin

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

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.

Install the agent

If you add the agent to a base image, you can make a single image change and Contrast will be available to all applications using that base image. Also, this way, updates will depend on the base image update. To do this:

Add the Contrast agent and basic configuration to a Docker base image, but don't enable it. Use /opt/contrast as your location. Optionally, you can change the URL to download agents from an internal repository. For example:
```
FROM BASE_IMAGE
ARG CONTRAST_AGENT_VERSION
ADD https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/$CONTRAST_AGENT_VERSION/contrast-agent-$CONTRAST_AGENT_VERSION.jar 
/opt/contrast/contrast.jar
```
You can pass a specific agent version at build time by replacing <YourAgentVersion> with the version number you want to download.
```
docker build --build-arg CONTRAST_AGENT_VERSION=<YourAgentVersion> -t image_with_contrast:tag .
```
Tip
If you want more flexibility to use any version of the Java agent, and to avoid automatic updates, apply the ADD instruction directly to an application's Docker image.
Enable Contrast in the application’s Docker image or container.

Configure the agent

Configuration of the Java agent follows this order of precedence. When installing into a container:

Use a YAML configuration file for common configuration so it can be placed in the base image. For example, common configuration might include redirecting logging to console output, proxy configuration, or performance tuning.
Here is a sample YAML configuration file:
```
agent:
  java:
    scan_all_classes: false
    scan_all_code_sources: false
  logger:
    stdout: true
```
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	`-Dcontrast.application.metadata`	CONTRAST__APPLICATION__METADATA
Application name	Specify the application name reported to Contrast	`-Dcontrast.agent.java.standalone_app_name`	CONTRAST__AGENT__JAVA__STANDALONE_APP_NAME
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

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.agent.java.standalone_app_name=APP \
-Dcontrast.application.group=APP_GROUP

Build the application image

For the agent to send data to Contrast, it needs agent authentication keys. To protect the agent credentials, you can utilize 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, Inc2020-05-28 22:36:29,910 [main STDOUT] INFO - Contact: support@contrastsecurity.com2020-05-28 22:36:29,910 [main STDOUT] INFO - License: Commercial2020-05-28 22:36:29,910 [main STDOUT] INFO - NOTICE: This Software and the patented inventions embodied within may only be used as part of2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security's commercial offerings. Even though it is made available through public2020-05-28 22:36:29,910 [main STDOUT] INFO - repositories, use of this Software is subject to the applicable End User Licensing Agreement2020-05-28 22:36:29,910 [main STDOUT] INFO - found at https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed between2020-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 User2020-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]