# Pivotal Cloud Foundry (PCF) Support

Adding the Sealights Java agent into your Pivotal Cloud Foundry environment (formerly VMWare Tanzu Application Services) is done by using the **standard CloudFoundry Java buildpack 4.39 or later**.

{% hint style="info" %}
​Complimentary information is detailed in <https://github.com/cloudfoundry/java-buildpack/blob/main/docs/framework-sealights_agent.md>
{% endhint %}

## Installing CF Java buildpack  <a href="#installing-cf-java-buildpack" id="installing-cf-java-buildpack"></a>

The `Java Buildpack` is a [Cloud Foundry](http://www.cloudfoundry.org/) buildpack for running JVM-based applications and is configured in one of the following ways:

{% tabs %}
{% tab title="Option A" %}
In the `manifest.yml` of your app, add the CloudFoundry Java buildpack

{% code overflow="wrap" lineNumbers="true" %}

```
---
applications:
-  name: yourApp
    buildpacks:
    - https://github.com/cloudfoundry/java-buildpack
```

{% endcode %}
{% endtab %}

{% tab title="Option B" %}
Add the buildpack through the command line

{% code overflow="wrap" lineNumbers="true" %}

```
cf push -b https://github.com/cloudfoundry/java-buildpack
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you need to create an **offline buildpack** without network access, you can do so following the instructions here: <https://github.com/cloudfoundry/java-buildpack#offline-package>
{% endhint %}

## Configuring the Sealights service in Java Buildpack <a href="#configuring-the-sealights-service-in-java-buildpack" id="configuring-the-sealights-service-in-java-buildpack"></a>

Setting up the Sealights Java buildpack integration involves a few straightforward steps:

1. **Create** a Sealights user-provided service and define its general settings (typically the `token`).
2. **Bind** your application to the Sealights service.
3. **Define** Sealights-specific parameters for your application (e.g., `lab_id`, `proxy`, etc.).
4. **Restage** the application to apply the changes.

While these steps can be automated through a **manifest** file using Cloud Foundry's native support for declaring services and environment variables, the following sections will focus on the equivalent **CLI-based workflow**, which is more commonly used in CI/CD automation scripts.

### Create your Sealights User-Provided service <a href="#create-your-sealights-user-provided-service" id="create-your-sealights-user-provided-service"></a>

Create a **Sealights User-Provided Service** and configure it with an **agent token**. This should be done once, before configuring the first application, as it allows you to manage the token at the service level.

{% code overflow="wrap" lineNumbers="true" %}

```shell
cf cups sealights-java -p '{"token":"ey…"}'
```

{% endcode %}

{% hint style="warning" %}
A different name for the user-provided service may be used, but it **MUST** include the word `sealights` (lowercase) for the integration to work
{% endhint %}

{% hint style="info" %}

* The token may later be changed using: `cf update-user-provided-service sealights-java -p '{"token":"ey…"}'` (or via the command shortcut `cf uups`)
* If you need to use a different token per application, you can also define it as part of the application parameters (see below)
  {% endhint %}

### Bind your application to your Sealights service <a href="#bind-your-application-to-your-sealights-service" id="bind-your-application-to-your-sealights-service"></a>

Bind the User-Provided Service with your application using the following command

{% code overflow="wrap" lineNumbers="true" %}

```sh
cf bind-service [app name] sealights-java
```

{% endcode %}

### Defining the Sealight's specific parameters  <a href="#defining-the-sealights-specific-parameters" id="defining-the-sealights-specific-parameters"></a>

If the build session ID, lab ID, proxy, or other settings need to be configured, you may either use one of the following options:

* hard-code them in `manifest.yml`:

{% code overflow="wrap" lineNumbers="true" %}

```yaml
env:
  JBP_CONFIG_SEALIGHTS_AGENT: '{lab_id: yourLabId, proxy: "http://myproxy.mycompany.int"}' 
```

{% endcode %}

* pass them as environment variables for the application via a dedicated command:

{% code overflow="wrap" lineNumbers="true" %}

```sh
cf set-env [my-application] JBP_CONFIG_SEALIGHTS_AGENT '{lab_id: "myLabId", proxy: "http://myproxy.mycompany.int"}'
```

{% endcode %}

* set up as environment variables via your administrative console:

  <figure><img src="https://4057366433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjqTCMRYvHhDgsdPLUnc%2Fuploads%2Fh4MQppCgZeJYsqeJ8Tqt%2Fimage-20220215-082611.png?alt=media&#x26;token=8b28ac5c-6d7b-4b19-9110-1e57c409ac74" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
`JBP_CONFIG_SEALIGHTS_AGENT` must be declared as a **User-Provided Environment Variable** (specific to the app instance) and not at the service level (such as Credential parameters, for example).
{% endhint %}

Available configuration keys are:

| Name               | Description                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build_session_id` | [generating-a-session-id](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/generating-a-session-id "mention")for the application. Leave blank to use the value embedded in the jar/war artifacts                                                                                         |
| `proxy`            | Specify an HTTP proxy used to communicate with the Sealights backend. This option is required when a corporate network prohibits communication with our cloud services. The default is to have no proxy configured and does not inherit from `http_proxy`/`https_proxy` or `http.proxyHost/https.proxyHost`, you must set this specifically if a proxy is needed. |
| `lab_id`           | Specify a Sealights Lab ID [running-parallel-tests-lab-id](https://docs.sealights.io/knowledgebase/setup-and-configuration/running-parallel-tests-lab-id "mention")                                                                                                                                                                                               |
| `auto_upgrade`     | Enable/disable agent auto-upgrade. Off by default.                                                                                                                                                                                                                                                                                                                |
| `version`          | <p>The version of Auto-reconfiguration to use. Candidate versions can be found in <a href="https://agents.sealights.co/pcf/index.yml">this listing</a>.<br>If <code>auto\_upgrade</code> is turned on, a different version may be downloaded and used at runtime</p>                                                                                              |

### Restage Application <a href="#restage-application" id="restage-application"></a>

To apply changes, you have to publish your application again, or simply restage it with the command [restage](https://cli.cloudfoundry.org/en-US/v7/restage.html)

{% code overflow="wrap" lineNumbers="true" %}

```sh
cf restage [app name]
```

{% endcode %}

{% hint style="success" %}
When the **application is up** and running and the **Sealights Listener agent is properly configured**, you can validate that it is running and communicating with your dashboard account from the ***Cockpit -> Live Agents Monitor*** screen.
{% endhint %}

## How to download the SL agent to CF from a Custom Repository  <a href="#how-to-download-the-sl-agent-to-cf-from-a-custom-repository" id="how-to-download-the-sl-agent-to-cf-from-a-custom-repository"></a>

By default, the Sealights PCF buildpack fetches the agent version from the official repository index at `https://agents.sealights.co/pcf/index.yml`. This `index.yml` file maps each agent version to its corresponding download URL, for example:

{% code overflow="wrap" lineNumbers="true" %}

```
#... (older)
4.0.2561: https://agents.sealights.co/sealights-java/sealights-java-4.0.2561.zip
4.0.2565: https://agents.sealights.co/sealights-java/sealights-java-4.0.2565.zip
4.0.2570: https://agents.sealights.co/sealights-java/sealights-java-4.0.2570.zip
#... (newer)
```

{% endcode %}

In scenarios where direct access to the default Sealights repository is restricted (e.g., due to internal security policies), you can **configure the buildpack to use a self-hosted, customized list of agent URLs**, allowing the agent to be downloaded from a custom repository (e.g., an internal Artifactory server) without the need to repackage the buildpack.

Here are the recommended steps to follow:

1. Create and **host your custom version** of the `index.yml` file that maps agent versions to internal URLs, for example:

{% code overflow="wrap" lineNumbers="true" %}

```
#...
4.0.2570: https://my-artifactory-server.mycompany.int/sealights/agents/java/sealights-java-4.0.2570.zip
#...
```

{% endcode %}

Alternatively, you can also point to the `agents` endpoint mirrored on your custom dashboard instance (`your-domain.sealights.co`) if accessible from your CF instances:

{% code overflow="wrap" lineNumbers="true" %}

```
#...
4.0.2570: https://<your-custom-domain>.sealights.co/agents/sealights-java/sealights-java-4.0.2570.zip
#...
```

{% endcode %}

**Ensure this** `index.yml` **file is publicly accessible to the buildpack** at a custom URL, e.g., `https://my-file-server.mycompany.int/sealights-pcf/index.yml`[.](https://my-file-server.mycompany.com/sealights-pcf/index.yml.)<br>

2. **Configure the Sealights buildpack to use your custom repository definition** by setting the base URL to your `index.yml` file as the `repository_root` in the `JBP_CONFIG_SEALIGHTS_AGENT` environment variable at the application level (developer) or platform level (operator):

{% code overflow="wrap" lineNumbers="true" %}

```sh
cf set-env my-app JBP_CONFIG_SEALIGHTS_AGENT '{ repository_root: "https://my-file-server.mycompany.int/sealights-pcf", lab_id: "myLabId"}'
```

{% endcode %}

This tells the buildpack to fetch the agent metadata from your custom `index.yml`.

3. With the custom configuration set, **push or restage your application** as usual.

{% hint style="warning" %}

* Your custom `index.yml` only needs to include the versions you intend to use.
* The `repository_root` must be the base path containing the `index.yml` file (without the filename itself).
* No changes to the actual buildpack source or packaging are required.
  {% endhint %}

## Sample configuration <a href="#sample-configuration" id="sample-configuration"></a>

#### Sample `Manifest.yml` <a href="#sample-manifest.yml" id="sample-manifest.yml"></a>

{% code overflow="wrap" lineNumbers="true" %}

```yaml
applications:
  - name: my-app
    memory: 1G
    buildpacks:
      - https://github.com/cloudfoundry/java-buildpack
    env:
      JBP_CONFIG_SEALIGHTS_AGENT: >
        {lab_id: "${SL_LAB_ID}", proxy: "${CF_PROXY}"}
    services:
      - sealights-java
```

{% endcode %}

#### Sample Deployment Script <a href="#sample-deployment-script" id="sample-deployment-script"></a>

{% code overflow="wrap" lineNumbers="true" %}

```javascript
#!/bin/bash
set -e

# Configurable values
APP_NAME="my-app"
SEALIGHTS_SERVICE="sealights-java"

# Retrieve secrets from a secrets vault (e.g., HashiCorp Vault)
export SL_LAB_ID="myLabId"
export CF_PROXY="http://myproxy.mycompany.int"
export SEALIGHTS_TOKEN=$(vault kv get -field=token secret/sealights)  # Replace with your vault command

# Create or update the user-provided service for Sealights
cf cups $SEALIGHTS_SERVICE -p '{"token":"'"$SEALIGHTS_TOKEN"'"}'

# Check for manifest.yml presence
if [ -f "manifest.yml" ]; then
  echo "manifest.yml found. Deploying using manifest..."
  cf push
else
  echo "manifest.yml not found. Proceeding with manual deployment..."
  cf push $APP_NAME -b https://github.com/cloudfoundry/java-buildpack
  # Set Sealights environment variables
  cf set-env $APP_NAME JBP_CONFIG_SEALIGHTS_AGENT '{lab_id: "'"$SL_LAB_ID"'", proxy: "'"$CF_PROXY"'"}'
  cf bind-service $APP_NAME $SEALIGHTS_SERVICE
  cf restage $APP_NAME
fi

# Optionally display recent logs and status
cf logs $APP_NAME --recent
cf app $APP_NAME
```

{% endcode %}

## Troubleshooting Sealights Buildpack Configuration <a href="#troubleshooting-sealights-buildpack-configuration" id="troubleshooting-sealights-buildpack-configuration"></a>

If your application is not instrumented as expected or you suspect issues with the Sealights buildpack integration, follow these recommended steps to identify and resolve common configuration problems.

#### Verify Sealights Buildpack Configuration <a href="#verify-sealights-buildpack-configuration" id="verify-sealights-buildpack-configuration"></a>

* Ensure that all required Sealights-related environment variables are defined (e.g., `JBP_CONFIG_SEALIGHTS_AGENT`, etc.).
* Confirm that the Sealights service is correctly **bound** to the application.

#### Analyze Application Logs <a href="#analyze-application-logs" id="analyze-application-logs"></a>

* Check the application logs using `cf logs <your-app-name>`.
* Search for the keyword `sealights` to identify log entries related to the agent or buildpack.
* Review any errors or warnings related to agent download, initialization, or configuration.

#### Connect to the Running CF Instance <a href="#connect-to-the-running-cf-instance" id="connect-to-the-running-cf-instance"></a>

Use `cf ssh <your-app-name>` to access the application container and perform the following validations:

1. Run the standard `ps -ef | grep java` command to find and validate the startup parameters of the Java process of your application. Look for the Sealights Java agent in the JVM parameters (e.g., `-javaagent:/path/to/sealights-java-agent.jar`).
2. Run the standard `env | grep SEALIGHTS` command to find and check the required environment variables. Ensure that Sealights-specific variables (e.g., `JBP_CONFIG_SEALIGHTS_AGENT`) are correctly set in the runtime environment.
3. Verify that the Sealights agent JAR was downloaded successfully and is not corrupted. If missing, try downloading the agent manually to test connectivity, then unzip the archive and inspect the content if needed.
4. If your application was built in your CI with Sealights Maven or Gradle plugins, ensure the `buildSessionId.txt` and `sltoken.txt` files are bundled within your deployed application. Depending on your setup, these files should reside in the application's working directory or embedded within the JAR.