Try JFrog
Guides
Contact SupportTry JFrog
  1. Install Individual Products
  2. Individual JFrog Products Installation
  3. Catalog Installation

Catalog Helm and OpenShift Installation

Install JFrog Catalog on Kubernetes or OpenShift via Helm as standalone or sub-chart of Platform/Xray chart.


This page describes how to install or upgrade JFrog Catalog using Helm on Kubernetes and OpenShift.

JFrog Catalog provides a centralized view of software packages and their security posture.

Starting with Xray chart version 103.111.9, Catalog is included as a dependent sub-chart of the JFrog Platform and Xray charts. Starting with Xray version 3.137.x, Catalog can also be deployed decoupled from Xray, allowing it to run independently for improved availability and scaling. Starting with Xray version 3.148.x, Catalog uses Valkey Sentinel as the default cache backend for high availability.

📘

Although Catalog can be installed as a standalone service, it is most commonly enabled and managed through the parent JFrog Platform or Xray Helm chart using values.yaml.

System Requirements

Verify that the nodes running the Catalog service meet the following minimum requirements:

ResourceRequirement
CPU2 cores minimum (4 cores recommended)
Memory6 GB RAM per node
DatabasePostgreSQL 13.x – 17.x
CacheValkey (required for Catalog 3.131.x and later)

Valkey Cache Modes

Catalog supports two Valkey deployment modes. The mode you use depends on your Xray version.

Xray VersionDefault ModeConfiguration
3.131.x – 3.147.xSingle-node Valkeyvalkey.enabled: true
3.148.x and laterValkey Sentinelvalkey.enabled: true and valkey.sentinel.enabled: true

From Xray 3.148.x onward, Valkey Sentinel is the default cache backend. It provides high availability through automatic failover and is recommended for all production environments. To enable Sentinel mode, valkey.enabled must be set to true - thesentinel block is a sub-configuration of Valkey and requires Valkey itself to be enabled.


Secure Configuration Using Kubernetes Secrets (Recommended)

To avoid storing sensitive keys in plain text, use Kubernetes Secrets for the joinKey and masterKey.

  1. Create the Secret
kubectl create secret generic jfrog-keys \
  --from-literal=join-key=<YOUR_JOIN_KEY> \
  --from-literal=master-key=<YOUR_MASTER_KEY> \
  -n <your-namespace>
  1. Reference the Secret in values.yaml
joinKeySecretName: jfrog-keys
masterKeySecretName: jfrog-keys

Kubernetes Installation (EKS, GKE, AKS, and Vanilla Kubernetes)

JFrog Platform (Umbrella Chart)

Xray 3.148.x and later (Valkey Sentinel — default)

xray:
  enabled: true
  catalog:
    enabled: true
    cache:
      enabled: true
    database:
      url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
      user: "catalog"
      password: "password"

  valkey:
    enabled: true
    sentinel:
      enabled: true

Xray 3.131.x – 3.147.x (single-node Valkey)

xray:
  enabled: true
  catalog:
    enabled: true
    cache:
      enabled: true
    database:
      url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
      user: "catalog"
      password: "password"

  valkey:
    enabled: true

JFrog Xray (Standalone Chart)

Xray 3.148.x and later (Valkey Sentinel — default)

catalog:
  enabled: true
  cache:
    enabled: true
  database:
    url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
    user: "catalog"
    password: "password"

valkey:
  enabled: true
  sentinel:
    enabled: true

Xray 3.131.x – 3.147.x (single-node Valkey)

catalog:
  enabled: true
  cache:
    enabled: true
  database:
    url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
    user: "catalog"
    password: "password"

valkey:
  enabled: true

JFrog Catalog (Standalone Installation)

Xray 3.148.x and later (Valkey Sentinel — default)

jfrogUrl: "https://jfrog.example.com"

joinKey: "YOUR_JOIN_KEY"
masterKey: "YOUR_MASTER_KEY"

cache:
  enabled: true

database:
  url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
  user: "catalog"
  password: "password"

valkey:
  enabled: true
  sentinel:
    enabled: true

Xray 3.131.x – 3.147.x (single-node Valkey)

jfrogUrl: "https://jfrog.example.com"

joinKey: "YOUR_JOIN_KEY"
masterKey: "YOUR_MASTER_KEY"

cache:
  enabled: true

database:
  url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
  user: "catalog"
  password: "password"

valkey:
  enabled: true

OpenShift Installation

On OpenShift, container and pod security contexts must be disabled to allow OpenShift to assign user IDs.

JFrog Platform (Umbrella Chart)

Xray 3.148.x and later (Valkey Sentinel — default)

xray:
  enabled: true
  catalog:
    enabled: true
    cache:
      enabled: true
    containerSecurityContext:
      enabled: false
    podSecurityContext:
      enabled: false
    database:
      url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
      user: "catalog"
      password: "password"

  valkey:
    enabled: true
    sentinel:
      enabled: true
      containerSecurityContext:
        enabled: false

Xray 3.131.x – 3.147.x (single-node Valkey)

xray:
  enabled: true
  catalog:
    enabled: true
    cache:
      enabled: true
    containerSecurityContext:
      enabled: false
    podSecurityContext:
      enabled: false
    database:
      url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
      user: "catalog"
      password: "password"

  valkey:
    enabled: true
    containerSecurityContext:
      enabled: false

JFrog Xray (Standalone Chart)

Xray 3.148.x and later (Valkey Sentinel — default)

catalog:
  enabled: true
  cache:
    enabled: true
  containerSecurityContext:
    enabled: false
  podSecurityContext:
    enabled: false
  database:
    url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
    user: "catalog"
    password: "password"

valkey:
  enabled: true
  sentinel:
    enabled: true
    containerSecurityContext:
      enabled: false

Xray 3.131.x – 3.147.x (single-node Valkey)

catalog:
  enabled: true
  cache:
    enabled: true
  containerSecurityContext:
    enabled: false
  podSecurityContext:
    enabled: false
  database:
    url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
    user: "catalog"
    password: "password"

valkey:
  enabled: true
  containerSecurityContext:
    enabled: false

JFrog Catalog (Standalone – OpenShift)

Xray 3.148.x and later (Valkey Sentinel — default)

jfrogUrl: "https://jfrog.example.com"

joinKey: "YOUR_JOIN_KEY"
masterKey: "YOUR_MASTER_KEY"

cache:
  enabled: true

database:
  url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
  user: "catalog"
  password: "password"

containerSecurityContext:
  enabled: false
podSecurityContext:
  enabled: false

valkey:
  enabled: true
  sentinel:
    enabled: true
    containerSecurityContext:
      enabled: false

Xray 3.131.x – 3.147.x (single-node Valkey)

jfrogUrl: "https://jfrog.example.com"

joinKey: "YOUR_JOIN_KEY"
masterKey: "YOUR_MASTER_KEY"

cache:
  enabled: true

database:
  url: "postgres://<DB_HOST>:5432/catalogdb?sslmode=disable"
  user: "catalog"
  password: "password"

containerSecurityContext:
  enabled: false
podSecurityContext:
  enabled: false

valkey:
  enabled: true
  containerSecurityContext:
    enabled: false

Install or Upgrade Using Helm

Update the Helm Repository

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

Install or Upgrade

JFrog Platform

helm upgrade --install jfrog-platform jfrog/jfrog-platform \
  -n jfrog \
  -f values.yaml

JFrog Xray

helm upgrade --install xray jfrog/xray \
  -n xray \
  -f values.yaml

Standalone Catalog

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

Verify the Installation

Verify Pod Status

kubectl get pods -n <your-namespace> | grep -E "catalog|valkey"

Verify Service Health

curl http://catalog-service:8046/catalog/api/v1/system/app_health

Expected response:

{
  "entitlements": {
    "entitled_for_catalog": true,
    "has_central_token": true
  },
  "db_connection_working": true,
  "status": "ok"
}

Related Topics