Distribution Single Node Docker Compose Installation

JFrog Installation & Setup Documentation
Content Type
Installation & Setup
ft:sourceType
Paligo

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Distribution System Requirements
Operating Systems and Platform Support

The following table lists the supported operating systems and the versions.

Product

Debian

RHEL

Ubuntu

Amazon Linux

Windows Server

Artifactory

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

2016 or 2019

Xray

10.x, 11.x

8.x, 9.x

20.04, 22.04

Distribution

10.x, 11.x

8.x, 9.x

20.04, 22.04

Insight

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

Pipelines

8.x

20.04, 22.04

Amazon Linux 2023

Build nodes only

Supported Platforms

The following table lists the supported platforms.

Product

x86-64

ARM64

Kubernetes

OpenShift

Artifactory

1.19+

4.13+

Xray

1.19+

4.13+

Distribution

1.19+

4.13+

Insight

1.19+

Pipelines

1.19+

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3+.

Kubernetes Sizing Requirements

We have included YAML files with different sizing configurations for Artifactory , Xray, and Distribution in our GitHub pages. You can use these YAML files when you set up your cluster.

ARM64 Support

Starting from version 7.41.4, Artifactory supports installation on ARM64 architecture through Helm and Docker installations. You must set up an external database as the Artifactory database since Artifactory does not support the bundled database with the ARM64 installation. Artifactory installation pulls the ARM64 image automatically when you run the Helm or Docker installation on the ARM64 platform.

ARM64 support is also available for Xray, Distribution and Insight.

Database and Third-Party Applications in Distribution

Distribution supports the following versions of PostgreSQL:

  • 16.x

  • 15.x

  • 14.x

  • 13.x

  • 12.x

Distribution HA requires an external database. Any change to configuration requires restarting of any Distribution node for changes to take effect for the whole Distribution cluster.

Distribution requires Redis and supports Redis 7.x. A supported Redis version is bundled with the Distribution installer.

Redis Password Restrictions

Redis password should contain only alphanumeric characters and should not contain any special characters.

Distribution Network Ports

Distribution uses the 8082 port by default for external communication.

Distribution uses the following internal ports by default for communication with JFrog Platform microservices.

Microservice

Port

Distribution Server

8080

Router

HTTP: 8082, 8046, 8049

gRPC: 8047

Redis

6379

PostgreSQL (if you use the bundled Postgres database)

5432

Observability

HTTP: 8036

gRPC: 8037

In addition, review the Docker requirements.

Docker Requirements

For Docker and Docker Compose installations, JFrog services require Docker 20.10.10 and above, and Docker Compose v1.24 and above to be installed on the machine where you want to run them.

For more information, see Docker and Docker Compose.

Follow these steps to install the product:

  1. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-distribution-<version>-compose.tar.gz

    .env file included within the Docker-Compose archive

    The .env file is used by docker-compose and is updated during installations and upgrades.

    Some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

  2. Create the following folder structure under JFROG_HOME.

    `-- [1020    1020  ]  var
    |-- [1020    1020  ]  data
    |   |-- [999      999  ]  postgres
    |   |   `-- [999      999  ]  data
    |   `-- [999      999  ]  redis
    |-- [1020    1020  ]  etc

  3. Copy the appropriate docker-compose templates from the templates folder to the extracted folder. Rename it as docker-compose.yaml.

    Requirement

    Template

    Distribution with externalised databases

    docker-compose.yaml

    Distribution with PostgreSQL

    docker-compose-postgres.yaml

    Docker for Mac

    When you use Docker Compose in Mac, /etc/localtime might not work as expected since it might not be a shared location in the docker-for-mac settings.

    You can remove the following line from the selected docker-compose.yaml file to avoid installation issues.

    - /etc/localtime:/etc/localtime:ro

  4. Update the .env file.

    You can enter the installation directory for Distribution. The default value is $HOME/.jfrog/distribution

    ROOT_DATA_DIR=

  5. Customize the product configuration.

    1. Set the Artifactory connection details.

    2. Customize the PostgreSQL Database connection details. (optional)

    3. Set any additional configurations (for example: ports, node id) using the Distribution system.yaml file.

      Note

      Ensure the host's ID and IP are added to the system.yaml. This is important to ensure that other products and Platform deployments can reach this instance.

  6. Start Distribution using docker-compose commands.

    docker-compose -p distribution logs
docker-compose -p distribution ps
docker-compose -p distribution up -d
docker-compose -p distribution down

  7. Access Artifactory from your browser at: http://SERVER_HOSTNAME/ui/.

    For example, on your local machine: http://localhost/ui/.

  8. Check the Distribution log.

    docker-compose -p distribution logs

    Configure log rotation of the console log

    The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.Configuring Log Rotation for Tomcat

Distribution Product Configuration

After installing and before running Distribution, you may set the following configurations.

Where to find the system configurations?

You can configure all your system settings using the system.yaml file located in the $JFROG_HOME/distribution/var/etc folder. For more information, see Distribution YAML Configuration.

If you don't have a System YAML file in your folder, copy the template available in the folder and name it system.yaml.

For the Helm charts, the system.yaml file is managed in the chart’s values.yaml.

Artifactory Connection Details for Distribution

Distribution requires a working Artifactory server and a suitable license.

The Distribution connection to Artifactory requires the following parameters.

  • jfrogUrl - URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. It is recommended to use DNS names rather than direct IPs. For example: http://jfrog.acme.com instead of http://10.20.30.40:8082.

    Set it in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

  • join.key - This is the secret key required by Artifactory for registering and authenticating the Distribution server.

    You can fetch the Artifactory joinKey (join Key) from the JPD UI in the Administration module | User Management | Settings | Join Key.

    Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

Add Signing Keys to JFrog Distribution

The JFrog Platform supports signing keys to establish trust with your clients for downloading your packages from Artifactory. Signing keys consist of a public and a private key pair, which are used for signing and verifying release bundles. When installing a new Edge, you will need to propagate the public keys to the new Edge. To learn about how to add and propagate keys, see GPG Signing.GPG Signing

Change PostgreSQL Database Credentials

Distribution comes bundled with a PostgreSQL Database out-of-the-box, which comes pre-configured with default credentials

To change the default credentials:

# Access PostgreSQL as the Distribution user adding the optional -W flag to invoke the password prompt
$ psql -d distribution -U distribution -W
  
# Securely change the password for user "distribution". Enter and then retype the password at the prompt.
\password distribution
  
# Verify the update was successful by logging in with the new credentials
$ psql -d distribution -U distribution -W

Set your PostgreSQL connection details in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

Change Redis Database Credentials

Redis Password Restrictions

Redis password should contain only alphanumeric characters and should not contain any special characters.

  1. Set the new password in the $JFROG_HOME/distribution/app/third-party/redis/redis.conf file.

    requirepass <new password>

    • Docker Compose

      The file is available at $JFROG_HOME/distribution/app/third-party/redis/redis.conf.

    • RPM/DEB

      The file is available at $JFROG_HOME/distribution/app/third-party/redis/redis.conf.

    • Linux Archive

      The file is available at $JFROG_HOME/distribution/app/third-party/redis/redis.conf.

  2. Set your Redis password in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

  3. For Helm installations, you can set the password in the values.yaml file.

    distribution:
 jfrogUrl: http://xx.xx.xxx.xx
 joinKey: 6a8d2eaa5eab7d6945c020245c98344b9b42b9665073a36c74645d52e565dce4
 persistence:
  enabled: true
redis:
 password: <password>

  4. Restart all the services.

    Docker Compose

cd jfrog-distribution-<version>-compose
docker-compose -p distribution restart
    RPM/DEB

service distribution restart / systemctl restart distribution.service
    Linux Archive

distribution/app/bin/distribution.sh restart