Catalog Installation

Install JFrog Catalog to provide vulnerability and license data for JFrog Curation.

How Catalog, Curation, and Xray Work Together

• Catalog provides package vulnerability and license data.
• Curation uses Catalog data to evaluate open source packages before they enter your development pipeline. Curation cannot function without Catalog.
• Xray continuously scans packages that are already in your environment for newly identified vulnerabilities and compliance issues.

Curation is a component of Xray and is installed with Xray. If your subscription includes Curation, you can enable it from the JFrog Platform UI. Catalog is installed and operated as a separate service.

Together, Curation and Catalog help prevent risky packages from entering your software supply chain, while Xray continuously monitors components already in use.

Architecture and Deployment

Choose a deployment topology based on the environment and expected load:

• POC and small-scale environments: Catalog and Xray can run on the same VM.
• Production environments: Deploy Catalog in a high availability (HA) configuration to prevent resource contention and provide service continuity.
• Catalog and Valkey: Installing Catalog and Valkey on the same VM is supported, but is not recommended for production. The production best practice is to run Catalog and Valkey on dedicated VMs.
• Database: Catalog can use the same database instance as Xray.

High Availability

• Catalog HA provides service continuity if a node fails. It isn't a disaster recovery solution.
• Catalog HA requires at least two Catalog nodes.
• Three Catalog nodes are recommended for high-load environments.
• Catalog nodes discover one another automatically through the router topology.
• Separating Catalog and Valkey onto dedicated VMs is the recommended deployment. A combined three-VM cluster, with Catalog and Valkey installed together on each VM, is also supported.

HA Installation and Upgrade

The HA install and upgrade steps match the single-node procedures. Install each additional Catalog node with the same method you used for the first node.

• RPM, Debian, Docker Compose, and Linux Archive: Follow Catalog Installation with Interactive Script. For upgrades, follow Catalog Upgrade.
• Helm and OpenShift: Follow Catalog Helm and OpenShift Installation. To enable HA, set catalog.replicaCount to 2 or higher under the catalog section in both the Xray and JFrog Platform chart values.

An HA cluster has the following requirements:

• The Master Key must be identical across all nodes in the cluster.
• All nodes must connect to the same external database instance.

Verify the HA Topology

After you add a node, confirm that it appears in the router topology. Run the following command from any router on an Artifactory or Xray VM.

curl -s http://localhost:8046/router/api/v1/topology/health | grep node_id | grep catalog

The new nodes appear in the output:

"node_id": "catalog-ip-10-90-122-0",
"node_id": "catalog-ip-10-90-122-0",
"node_id": "catalog-ip-10-90-98-95",
"node_id": "catalog-ip-10-90-98-95",

Reference Architecture

Isolated Clusters (Catalog & Valkey)

Preferred for production

Combined HA cluster

While this configuration reduces VM count, it may induce resource contention between Catalog and Valkey components. Deployment in this mode requires careful monitoring and is advised only with appropriate caution.

Resource Requirements

VM Specifications - Native Installer

Resource Specifications - Helm Installer

For Kubernetes resource allocation, refer to the Xray Sizing Guide in the JFrog Helm charts repository.

Database Specifications

Catalog can share the same database instance as Xray. For database sizing, throughput, and IOPS requirements, see the JFrog Xray Hardware Sizing Matrix.

Network Ports

In a restricted environment, open the following ports so Catalog can join the JFrog Platform, sync metadata, and serve Curation package risk queries.

VM Installations

Applies to RPM, Debian, Linux Archive, and Docker Compose installations.

Ingress, into the Catalog host:

Egress, from the Catalog host:

Ports 7049 (Traefik API) and 8088 (Catalog HTTP) are used internally on localhost and do not require firewall rules.

Kubernetes Installations

Applies to Helm and OpenShift installations.

Ingress, into the Catalog pod:

Egress, from the Catalog pod:

In Kubernetes, the inter-service ports 7046 and 7047 stay inside the pod and do not need to be exposed externally.

Port Considerations

• The JFrog Platform URL port, 443 or 8082, depends on whether a reverse proxy is in front of Artifactory. Use the port that matches your shared.jfrogUrl configuration.
• The PostgreSQL port 5432 is the default. Use the port from your shared.database.url if it differs.
• The Artifactory and Access host must reach the Catalog host on the ingress port, 7082 or 8082, for cluster join validation.

Cache Configuration

Catalog supports the following cache options:

• Bring your own cache: Use an existing compatible cache service, such as Amazon ElastiCache or a managed Redis service.
• Bundled cache: Install the bundled Valkey service.

Use only one cache installation type in an environment. Do not mix bring-your-own and bundled cache nodes in the same deployment.

For production, deploy the cache separately from Catalog to reduce resource contention. See Valkey Installation with Interactive Script and Valkey HA Installation for installation guidance.

Monitoring and Maintenance

Monitor the following areas after installation:

• Request latency: The target response time is less than 100 ms with Valkey enabled. Without Valkey, expect response times of approximately 100–300 ms.
• Integration load: Monitor Catalog performance when the Artifactory request rate exceeds 100 requests per second.
• Service dependencies: Catalog curation services depend on Xray and Artifactory availability.
• Data freshness: Catalog refreshes cached data through background cache invalidation. Verify data freshness in the UI footer or by using REST API queries.
• Health: Use the Catalog application health endpoint and REST APIs for health checks and system diagnostics. Refer here for the details of health check

Installation Methods

Install Catalog using one of the following methods:

1. Interactive Script for VM-based installations.
2. Helm and OpenShift for Kubernetes and OpenShift installations.

Related Topics

• Catalog Installation with Interactive Script
• Catalog Helm and OpenShift Installation
• PostgreSQL for JFrog Catalog
• Valkey Installation with Interactive Script
• Valkey HA Installation
• Upgrading JFrog Catalog
• Product Dependencies Matrix
• JFrog Xray Hardware Sizing Matrix