Distribution Upgrade from Version 2.x to 2.x

⚠️

Warning

Before you upgrade, verify that the operating system version you use is supported. See System Requirements for details on operating system support.

The following upgrade methods are supported:

• Interactive Script (recommended)
• Manual RPM / Debian
• Linux Archive Upgrade
• Helm

Interactive Script Upgrade (recommended)

The installer script works with all supported upgrade methods (RPM, Debian, and Docker Compose). It provides you an interactive way to install Distribution and its dependencies.

1. Download Distribution (RPM, Debian, or Docker Compose).

2. Stop the service.

   systemd

   Bash

   sudo systemctl stop distribution.service

   systemv

   Bash

   sudo service distribution stop

   Docker Compose

   Navigate to the directory containing your docker-compose.yaml and run:

   Bash

   docker-compose down

3. Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.

   Note: For Docker Compose upgrades, merge your customizations from the current docker-compose.yaml file into the newly extracted docker-compose.yaml.

📘

Note

Copy the contents of the .env file in the previous installation to the newly created .env file in this archive without copying the versions, as this will affect the upgrade.

4. Run the installer script.

   Note: If required, the script prompts for mandatory inputs, including the jfrogURL (custom base URL) and joinKey.

   RPM/DEB

   Bash

   sudo ./install.sh

   Docker Compose

   Bash

   sudo ./config.sh

5. Start and manage the Distribution service.

   systemd

   Bash

   sudo systemctl start distribution.service

   systemv

   Bash

   sudo service distribution start

   Docker Compose

   Navigate to the directory containing your new docker-compose.yaml and run:

   Bash

   docker-compose up -d

6. Access Distribution from your browser at: http://<jfrogUrl>/ui/, click the Distribution tab in the Platform module in the UI.

7. Check the Distribution log.

   Bash

   tail -f $JFROG_HOME/distribution/var/log/console.log

Manual RPM/Debian Upgrade

1. Download Distribution (RPM or Debian).

2. Stop the current server.

   systemd

   Bash

   sudo systemctl stop distribution.service

   systemv

   Bash

   sudo service distribution stop

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

4. Install Distribution using the package from the extracted archive.

   RPM

   Bash

   sudo rpm -Uvh distribution/distribution.rpm

   Debian

   Bash

   sudo dpkg -i distribution/distribution.deb

5. Start and manage Distribution.

   systemd

   Bash

   sudo systemctl start distribution.service

   systemv

   Bash

   sudo service distribution start

6. Access Distribution from your browser at: http://<jfrogUrl>/ui/, click the Distribution tab in the Platform module in the UI.

7. Check the Distribution log.

   Bash

   tail -f $JFROG_HOME/distribution/var/log/console.log

Linux Archive Upgrade

1. Stop the current server.

   Bash

   $JFROG_HOME/distribution/app/bin/distribution.sh stop

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

   Bash

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

3. Set the path to the extracted directory.

   Bash

   export JF_NEW_VERSION=<path to extracted folder, e.g., jfrog-distribution-<version>-linux>

4. Replace the existing $JFROG_HOME/distribution/app with the new app folder.

   Bash

   rm -rf $JFROG_HOME/distribution/app
   cp -r $JF_NEW_VERSION/app $JFROG_HOME/distribution/
   rm -rf $JF_NEW_VERSION
   chown -R distribution:distribution $JFROG_HOME/distribution/app

📘

Note

Verify that the password specified in the requirepass field in $JFROG_HOME/distribution/var/etc/redis/redis.conf (for more information, see Redis documentation) and the redis.password field in $JFROG_HOME/distribution/var/etc/system.yaml are the same.

5. Start the Distribution service.

   Run the following command as the distribution user.

   Bash

   $JFROG_HOME/distribution/app/bin/distribution.sh start

6. Access Distribution from your browser at: http://<jfrogUrl>/ui/, click the Distribution tab in the Platform module in the UI.

7. Check the Distribution log.

   Bash

   tail -f $JFROG_HOME/distribution/var/log/console.log

Helm Upgrade

Upgrading to Distribution 2.37.0 or Later

When upgrading from a version prior to 2.37.0, a pre-upgrade webhook (distribution-upgrade-hook) is automatically executed. This webhook handles the migration by deleting the existing StatefulSet with --cascade=orphan (preserving running pods) to allow the updated spec — which no longer includes Redis — to be applied cleanly.

In most cases, no manual intervention is required. However, if the hook job fails (for example, due to RBAC permissions or image pull issues), you may need to manually delete the StatefulSet before retrying the upgrade:

kubectl delete statefulset <release-name>-distribution --cascade=orphan -n <namespace>

📘

Note

Because of breaking changes in the PostgreSQL Helm chart, migrate the database from the old to the new database.

📘

Note

Downtime is required to perform an upgrade.

📘

Note

Before upgrading Distribution, complete the following.

1. Upgrade JFrog Artifactory to v7.x.

2. If you use the default PostgreSQL (postgresql.enabled=true), pass the previous 9.x or 10.x postgresql.image.tag and databaseUpgradeReady=true. Also delete the existing PostgreSQL subchart statefulset before the Helm upgrade, because the 9.x chart version of PostgreSQL has breaking changes.

   Run helm upgrade with the following values set.

1. Update the existing deployed version to the updated version.

2. If Distribution was installed without providing a value to postgresql.postgresqlPassword (the password was autogenerated), follow these instructions.

   1. Get the current password by running the following.
   2. Upgrade the release by passing the previously auto-generated secret.

3. If Distribution was installed without providing a value to rabbitmq.rabbitmqPassword/rabbitmq-ha.rabbitmqPassword (the password was autogenerated), follow these instructions.

   1. Get the current password by running the following.
   2. Upgrade the release by passing the previously auto-generated secret.

4. If Distribution was installed with all of the default values (e.g., with no user-provided values for Rabbit/Postgres), follow these steps.

   1. Retrieve all current passwords (RabbitMQ/PostgreSQL) as explained in the above section.
   2. Upgrade the release by passing the previously auto-generated secrets.

   Migration Process

The recommended migration process is a full database export and import of PostgreSQL.

1. Block user access to Distribution (but do not shut down).

2. Get the service name OLD_PG_SERVICE_NAME using the command below. For example: OLD_PG_SERVICE_NAME as <OLD_RELEASE_NAME>-postgresql.

3. Save the previous password OLD_PG_SERVICE_NAME or extract it from the secret of the existing PostgreSQL pod.

4. Install the new Distribution version with 0 replicas.

   A new PostgreSQL pod will be deployed and started. The Distribution pod will be deployed but not started, since the replica count is 0.

   For example.

5. Connect to the new PostgreSQL pod (you can obtain the name by running kubectl get pods).

6. Once logged in, create a dump file from the previous database using pg_dump, and connect to the previous PostgreSQL chart.

   After running the command above, you should be prompted for a password; this password is the previous chart password (OLD_PASSWORD). This operation could take some time depending on the database size.

7. Once you have the backup file, you can restore it with a command like the one below.

8. After running the command above, you will be prompted for a password; this is the current chart password. This operation could take some time depending on the database size.

9. Run the command helm upgrade to bring up Distribution.

10. Run the following command to remove the old Distribution deployment and Helm release.

11. Access Distribution from your browser at: http://<jfrogUrl>/ui/, then go to the Security & Compliance tab in the Platform module in the UI.

12. Check the status of your deployed Helm releases.

    Distribution should now be ready for use.