Install JFrog Catalog with Helm and OpenShift

Installation Type:

Supported Xray chart version 103.111.9 and above

Helm (Kubernetes)

Install

Note

In our documentation, we use oc commands for code snippets related to OpenShift installation, but kubectl commands will also work.

Starting Xray Version 3.131.x Valkey has been added as a cache service in Catalog. Installation requires cache and Valkey to be enabled. The following sample shows how to provide these in the values.yaml file:

catalog:
  enabled: true
  cache:
    enabled: true

valkey:
  enabled: true

Add the charts.jfrog.io to your Helm client.

helm repo add jfrog https://charts.jfrog.io

Update the repository.
```
helm repo update
```
Installation requires a JFrog url, join key and a master key. You can pass the join key along with the Helm install/upgrade command or pass it in a values.yaml file. The following sample shows how to provide a join key in the values.yaml file.
```
jfrogUrl: http://art-artifactory.art:8082
joinKey: EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE
masterKey: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
```
Alternatively, you can manually create secrets containing the join key and master key, and then pass them to the template during install/upgrade. The keys must be named join-key and master-key.
```
oc create secret generic joinkey-secret
--from-literal=join-key=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>
```
```
oc create secret generic masterkey-secret
--from-literal=master-key=<YOUR_PREVIOUSLY_RETRIEVED_MASTER_KEY>
```
The following example shows the values.yaml file with the join key and master key secret.
```
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
```

Installation requires configurations for an external PostgreSQL database. Below is an example configuration.

database:
  url: postgres://my-postgresql:5432/catalogdb?sslmode=disable
  user: catalog
  password: catalog

The introduction of extraSystemYaml enables users to modify components of the system.yaml configuration post-template evaluation. It allows users to seamlessly customize specific aspects of the system.yaml without duplicating the entire configuration file.
```
extraSystemYaml:
  shared:
    application:
      level: debug
```
Run the Helm install command to proceed with the installation. The following command shows how to pass the required values through a values.yaml file.
```
helm upgrade --install catalog jfrog/catalog --namespace catalog -f values.yaml
```
To access the logs, find the name of the pod using the following command:
```
oc --namespace <your namespace> get pods
```

To get the container logs, run the following command:

oc --namespace <your namespace> logs -f <name of the pod>

Upgrade

Modify the custom values file, then use the following command:

helm upgrade --install catalog jfrog/catalog --namespace catalog -f values.yaml

Helm (OpenShift)

catalog:
  enabled: true
  containerSecurityContext:
    enabled: false
  podSecurityContext:
    enabled: false
  cache:
    enabled: true
valkey:
  enabled: true

Add the charts.jfrog.io to your Helm client.

helm repo add jfrog https://charts.jfrog.io

Update the repository.
```
helm repo update
```
Installation requires a JFrog url, join key and a master key. You can pass the join key along with the Helm install/upgrade command or pass it in a values.yaml file. The following sample shows how to provide a join key in the values.yaml file.
```
jfrogUrl: http://art-artifactory.art:8082
joinKey: EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE
masterKey: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
```
Alternatively, you can manually create secrets containing the join key and master key, and then pass them to the template during install/upgrade. The keys must be named join-key and master-key:
```
oc create secret generic joinkey-secret --from-literal=join-key=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>
```
```
oc create secret generic masterkey-secret --from-literal=master-key=<YOUR_PREVIOUSLY_RETRIEVED_MASTER_KEY>
```
The following example shows the values.yaml file with the join key and master key secret.
```
joinKeySecretName: joinkey-secret
masterKeySecretName: masterkey-secret
```
When you deploy Catalog helm chart on an OpenShift cluster, you need to disable the securityContext and containerSecurityContext. Default OpenShift functionality automatically assigns an arbitrary UID block associated with the project.
Set the following values in the values.yaml so that you can pass it along with the installation.
```
securityContext:
  enabled: false
containerSecurityContext:
  enabled: false
```
To make PostgreSQL work on OpenShift, disable the securityContext and containerSecurityContext in thevalues.yamlfile, and set the following values:
```
podSecurityContext:
 enabled: false
containerSecurityContext:
 enabled: false
```
Run the Helm install command to proceed with the installation. The following command shows how to pass the required values through a values.yaml file.
```
helm upgrade --install catalog jfrog/catalog --namespace catalog -f values.yaml
```
To access the logs, find the name of the pod using the following command:
```
oc --namespace <your namespace> get pods
```

To get the container logs, run the following command:

oc --namespace <your namespace> logs -f <name of the pod>

Verifying Installation with a Health Check

After installing the JFrog Catalog, you can verify that it is properly configured and operational by using the app health API. This provides a quick status check on key aspects of the service, ensuring that the necessary entitlements, database connections, and central connectivity are in place.

API Request

Send a GET request to the following endpoint

GET <catalog-service>/api/v1/system/app_health

No authentication is required.

Example request:

https://localhost:8046/catalog/api/v1/system/app_health

API Response

A JSON object will be returned, detailing the system’s health status. The status field will indicate whether the setup is functioning correctly ("ok") or if issues exist ("not ok").

Example Response

{
  "entitlements": {
    "entitled_for_catalog": true,
    "has_central_token": true,
    "token_expired": false,
    "token_expiration": "2025-08-26T17:13:48Z"
  },
  "central": {
    "central_connection_working": true,
    "pinged_central": "node-id"
  },
  "db_connection_working": true,
  "status": "ok"
}

If the response indicates any issues, review the installation steps and configuration to resolve them before proceeding.