Installing JFrog Catalog with Interactive Script

Installation types: Install the following prerequisites independently of the JFrog Catalog installation.

Installation types:

Docker compose
RPM or Debian
Linux Archive

Prerequisites

Install the following prerequisites independently of the JFrog Catalog installation.

Valkey

Please follow the instructions given here for installing Valkey if a cache is required.

PostgreSQL

Minimum system requirements

catalog_cpus=1
catalog_ram_gb=2
catalog_disk_gb=100

Subscription Type: Enterprise X

Supported from:

Artifactory - 7.90.12 (for the catalog new service MFE)
Xray version 3.107.0 and above (with MFE fixes)

📘
Note
Xray and JFrog Catalog are packaged in a single tarball for RPM/Deb, Linux, and Docker compose installers. You will find the Catalog folder for the latest release version when you extract the Xray tarball.

Complete the following steps to install the product.

Extract the contents of the compressed Xray archive and go to the catalog folder.

cd jfrog-catalog<version>-compose
Install

Docker Compose

After starting up Valkey, add a cache section to the system.yaml of Catalog with Valkey password:
```
shared:
  cache:
    enabled: true
    connectionString: redis://<IP>:6379
    parameters: mode=single;password=<VALKEY_PASSWORD>
    defaultKeyExpirationSecs: 3600
    maxWarmupKeys: 1000
    warmupPoolSize: 10
```
Run the installer script ./config.sh and follow the instructions. The script prompts you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey

📘
Note
The .env file is used by docker-compose and is updated during installations and upgrades. Update the .env file in the jfrog-catalog <version>-compose dir to override the image registry if needed.
The system.yaml file will be available under the data dir (under path var/etc/system.yaml) defined in the env file.

Native (RPM/DEB)

Extract the contents of the compressed Xray archive and go to the Catalog folder.cd jfrog-catalog <version>-deb/rpm
Run the installer script ./install.sh and follow the instructions.

If Valkey is required, before starting up Catalog, add a cache section to the system.yaml of Catalog with Valkey password:

shared:
  cache:
    enabled: true
    connectionString: redis://localhost:6379
    parameters: mode=single;password=<VALKEY_PASSWORD>
    defaultKeyExpirationSecs: 3600
    maxWarmupKeys: 1000
    warmupPoolSize: 10
    warmupDBMaxOpenConns: 10
    warmupDBMaxIdleConns: 5
    invalidationPoolSize: 5
    invalidationIntervalSecs: 60

Linux Archive

Extract the contents of the compressed Xray archive. You will find the Catalog folder there. Move it into the catalog directory. (/opt/jfrog/catalog)

📘
Note
OS user permissions for Linux archive When running catalog, the installation script creates a user called catalog by default, which must have run and execute permissions on the installation directory. We recommend that you extract the catalog download file into a directory that gives run and execute permissions to all users such as /opt . for eg: 1. tar -xvf jfrog-xray-<version>-linux.tar.gz 2. mv jfrog-catalog-<version>-linux catalog 3. mkdir -p /opt/jfrog 4. mv catalog /opt/jfrog

Run the installer script (/opt/jfrog/catalog/app/bin/install.sh). The script prompts you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey and masterKey, PostgreSQL database details.

If Valkey is required, before starting up Catalog, add cache section to the system.yaml of Catalog with Valkey password:

shared:
  cache:
    enabled: true
    connectionString: redis://localhost:6379
    parameters: mode=single;password=<VALKEY_PASSWORD>
    defaultKeyExpirationSecs: 3600
    maxWarmupKeys: 1000
    warmupPoolSize: 10
    warmupDBMaxOpenConns: 10
    warmupDBMaxIdleConns: 5
    invalidationPoolSize: 5
    invalidationIntervalSecs: 60

After the installation is complete, follow the onscreen instructions to start the Catalog service.

For example:

for eg: 
chown -R catalog:catalog /opt/jfrog/catalog
su - catalog
/opt/jfrog/catalog/app/bin/catalog.sh start   // options - start/ stop/ restart

Install as a service (optional)

If you want JFrog Catalog to be installed as a service with the Linux Archive installer, run installService.sh under the app/bin folder and then start catalog as a service shown below.
```
systemctl start catalog.service
```

Start Catalog Service

Docker Compose
```
docker-compose -p catalog up -d
```
RPM or Debian
```
systemctl start catalog.service
```

Linux Archive

Through script:
/opt/jfrog/catalog/app/bin/catalog.sh start   // options - start/ stop/ restart

Through service
systemctl start catalog.service

Access Catalog from your browser at:

http://<jfrogUrl>:port/ui/catalog/packages/overview

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.

Updated 5 days ago