Upgrading Distribution

Overview

The procedure to upgrade Distribution depends on your installation type. We strongly recommend reading through this page before proceeding with your upgrade.

Before you upgrade Distribution please refer to additional information on supported platforms, browsers and other requirements, and the system architecture.

Important

Make sure to use the same upgrade method (RPM, Debian, Docker, etc.) as the one you initially used to install Distribution.

To ensure you can restore your Distribution and database in case you encounter any issues during the upgrade process, we strongly recommend that you make sure your system and database backups are up to date.

Upgrading to 2.x for the first time?

It is recommended that you first review what's new with the latest JFrog Platform. Review the breaking changes, deprecated features and more.

Artifactory and Distribution Pairing

The upgrade to the JFrog Platform requires mapping a source Artifactory to a single Distribution service. If you are creating and distributing release bundles from multiple source Artifactory instances and one Distribution instance, you will now need to deploy a Distribution service in every JPD that contains these source Artifactory instances. If your Mission Control instance is part of another JPD, you'll need to register it in the new Distribution instance. See details here.

Upgrade Steps

The upgrade procedure involves the following main steps:

Download Distribution (Docker Compose, RPM, Debian).
Stop the Distribution service
Install Distribution according to the installer distribution type.
Check the Migration Log and review system.yaml to validate the migration was successful (only for upgrading from v2.x).
Start the service using the start scripts or OS service management.
Check the Distribution Log for the status of the service.

Default Home Directory / $JFROG_HOME

The default Distribution home directory is defined according to the installation type. For additional details see the Product Directory Structure page.

Note: This guide uses $JFROG_HOME to represent the JFrog root directory containing the deployed product.

JFrog Subscription Levels

SELF-HOSTED

_ENTERPRISE+

Page Contents

Upgrading from Version Below 1.6

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

To upgrade from a version below 1.6.x, you first need to upgrade to version 1.6.x as described in the Upgrading Distribution 1.x documentation, and then continue to upgrading from version 1.6 to 2.x.

Upgrading from Version 1.6 to 2.x

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

JFrog Distribution v2.x is only compatible with JFrog Artifactory v7.x. To upgrade, you must first install JFrog Artifactory 7.x.

There are several new concepts introduced in Distribution 2.x, improving the installation and customization process.

The following upgrade methods are supported:

Interactive Script (recommended)
Manual RPM
Manual Debian

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.

Download Distribution

Stop the service.

Docker - Stop and remove old containers

distribution stop
docker ps -a --format '{{.Names}}' | grep ^distribution_* | xargs docker rm -f

Linux

cd /opt/jfrog/distribution/scripts
./distribution.sh stop

Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-distribution-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-distribution-<version>-<compose|rpm|deb>
```
.env file included within the Docker-Compose archive

This .env file is used by docker-compose and is updated during installations and upgrades.
Notice that some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.
Run the installer script.
Note: the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Compose
```
./config.sh
```
RPM/DEB
```
./install.sh
```
Check that the migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/distribution/var/log/migration.log file.
2. system.yaml configuration: $JFROG_HOME/distribution/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.

Start and manage the Distribution service.

systemd OS

systemctl start|stop distribution.service

systemv OS

service distribution start|stop

Docker Compose

cd jfrog-distribution-<version>-compose# Starting from Distribution 2.5.x Redis has been moved to a compose file of its own, this needs to be started before starting other services
docker-compose -p distribution-redis -f docker-compose-redis.yaml up -d

# Starting from 2.5.x, PostgreSQL needs to be started before starting the other services.
docker-compose -p distribution-postgres -f docker-compose-postgres-9-6-10v.yaml up -d

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

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

Check Distribution Log.

Linux

tail -f $Product Directory Structure/var/log/console.log

Manual RPM Upgrade

The RPM installation bundles Distribution and all its dependencies. It is provided as native RPM packages, where Distribution and its dependencies must be installed separately. Use this if you are automating installations.

Download Distribution.

Stop the current server.

cd /opt/jfrog/distribution/scripts
./distribution.sh stop

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

tar -xvf jfrog-distribution-<version>-rpm.tar.gz
cd jfrog-distribution-<version>-rpm

Install Distribution as a service on Red Hat compatible Linux distributions, as a root user.
```
yum -y install ./distribution/distribution.rpm
```
Check that the migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/distribution/var/log/migration.log file.
2. system.yaml configuration: $JFROG_HOME/distribution/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.
Set the Artifactory connection details.
Distribution requires a working Artifactory server and a suitable license. The Distribution connection to Artifactory requires 2 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 or 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 | Security | 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.
Make sure the third party services are running.
PostgreSQL
If you have installed the PostgreSQL database packaged as part of 1.x, you can continue to use it. Use the following command to start and stop your PostgreSQL service.
Notice: the ./distribution.sh stop all command, used in Distribution 1.x versions cannot be used in version 2.x.
service postgresql-9.6 start|stop|status
Redis
This will be available from the previous install. Use the following commands to start and stop your service.
Red Hat / CentOS
service redis start|stop|status
Debian / Ubuntu
service redis-server start|stop|status

Start and manage Distribution.

systemd OS

systemctl start|stop distribution.service

systemv OS

service distribution start|stop

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

Check the Distribution Log.

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

Manual Debian Upgrade

The Debian upgrade bundles Distribution and all its dependencies. It is provided as native Debian packages, where Distribution and its dependencies must be installed separately. Use this if you are automating installations.

Download Distribution.

Stop the current server.

cd /opt/jfrog/distribution/scripts
./distribution.sh stop

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

tar -xvf jfrog-distribution-<version>-deb.tar.gz
cd jfrog-distribution-<version>-deb

Install Distribution as a service on a Debian compatible Linux distributions, as a root user.
Run Installation
```
dpkg -i ./distribution/distribution.deb
```
Check that the migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/distribution/var/log/migration.log file.
2. system.yaml configuration: $JFROG_HOME/distribution/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.
Set the Artifactory connection details.
Distribution requires a working Artifactory server and a suitable license. The Distribution connection to Artifactory requires 2 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 or 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 | Security | 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.
Make sure the third party services are running.
PostgreSQL
If you have installed the PostgreSQL database packaged as part of 1.x, you can continue to use it. Use the following command to start and stop your PostgreSQL service.
Notice: the ./distribution.sh stop all command, used in Distribution 1.x versions cannot be used in version 2.x.
service postgresql-9.6 start|stop|status
Redis
This will be available from the previous install. Use the following commands to start and stop your service.
Red Hat / CentOS
service redis start|stop|status
Debian / Ubuntu
service redis-server start|stop|status

Start and manage Distribution.

systemd OS

systemctl start|stop distribution.service

systemv OS

service distribution start|stop

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

Check the Distribution Log.

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

Start and manage Distribution.
```
service distribution start|stop
```
Access Distribution from your browser at: http://<jfrogUrl>/ui/, go the Distribution tab in the Application module in the UI.

Check the Distribution Log.

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

Post-Upgrade Steps

Once the upgrade is complete.

Migrating Release Bundle Metadata to the Distribution Services

The new JFrog Platform requires Distribution to be connected to a single Source Artifactory instance, as part of a JPD.

If you had one Distribution instance connected to more than one Source Artifactory instances, use the Export and Import Release Bundle Metadata REST API commands to move to this new requirement after the upgrade process. For more information, see Upgrading Distribution.

Upgrading from Version 2.x to 2.x

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

The following upgrade methods are supported:

Interactive Script (recommended)
Manual RPM / Debian
Linux Archive
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.

Download Distribution (RPM, Debian or Docker Compose).

Stop the service.

Systemd OS

systemctl stop distribution.service

Systemv OS

service distribution stop

Docker - Stop and remove old containers

cd jfrog-distribution-<version>-compose
docker-compose -p distribution down

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, make sure to merge your customizations in your current docker-compose.yaml file to the new extracted version of the docker-compose.yaml file.
```
tar -xvf jfrog-distribution-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-distribution-<version>-<compose|rpm|deb>
```
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.
Run the installer script.
Note: if needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Compose
```
./config.sh
```
RPM/DEB
```
./install.sh
```

Start and manage the Distribution service.

systemd OS

systemctl start|stop

distribution.service

systemv OS

service distribution start|stop

Docker Compose

cd jfrog-distribution-<version>-compose# Starting from Distribution 2.5.x Redis has been moved to a compose file of its own, this needs to be started before starting other services
docker-compose -p distribution-redis -f docker-compose-redis.yaml up -d

# Starting from 2.5.x, PostgreSQL needs to be started before starting the other services.
if PostgreSQL 9.6.11 running use -   docker-compose -p distribution-postgres -f docker-compose-postgres-9-6-10v.yaml up -d
if PostgreSQL 10.13  running use -   docker-compose -p distribution-postgres -f docker-compose-postgres-10-13v.yaml up -d
if PostgreSQL 12.3   running use -   docker-compose -p distribution-postgres -f docker-compose-postgres.yaml up -d

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

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

Check Distribution Log.

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

Manual RPM/Debian Upgrade

Download Distribution (RPM or Debian)

Stop the current server.

systemd OS

systemctl stop distribution.service

systemv OS

sservice distribution stop

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

tar -xvf jfrog-distribution-<version>-<rpm|deb>.tar.gz
cd jfrog-distribution-<version>-<rpm|deb>

Install Distribution as a service on Red Hat compatible Linux distributions, as a root user.
rpm
```
yum -y install ./distribution/distribution.rpm
```
Debian
```
dpkg -i ./distribution/distribution.deb
```

Start and manage Distribution.

systemd OS

systemctl start|stop distribution.service

systemv OS

service distribution start|stop

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

Check Distribution Log.

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

Linux Archive Upgrade

Stop the current server.

Stop Distribution

# Export variables to simplify commands - set JFROG_HOME to current installed directory
export JFROG_HOME=/opt/jfrog
cd $JFROG_HOME/distribution/app/bin
./distribution.sh stop

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

Untar

mv jfrog-distribution-<version>-linux.tar.gz /opt/jfrog/
cd /opt/jfrog
tar -xf jfrog-distribution-<version>-linux.tar.gz

Replace the existing $JFROG_HOME/distribution/app with the new app folder.
Upgrade
```
export JF_NEW_VERSION=/opt/jfrog/jfrog-distribution-<version>-linux

# Remove app
rm -rf $JFROG_HOME/distribution/app

# Copy new app
cp -fr $JF_NEW_VERSION/app $JFROG_HOME/distribution/

# Remove extracted new version
rm -rf $JF_NEW_VERSION

chown -R distribution:distribution /opt/jfrog/distribution/app 
```
Verify that the password specified in the requirepass field in $JFROG_HOME/distribution/var/etc/redis/redis.conf (for more information, refer to https://redis.io/docs/manual/config/) and the redis.password field in $JFROG_HOME/distribution/etc/system.yaml are the same.
Manage Distribution.
Run the following command as the distribution user.
```
$JFROG_HOME/distribution/app/bin/distribution.sh start|stop
```
Access Distribution from your browser at: http://<jfrogUrl>/ui/, go the Dashboard tab in the Application module in the UI.

Check Distribution Log.

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

Helm Upgrade

Due to breaking changes in the PostgreSQL Helm chart, you will need to migrate the database from the old to the new database.

Downtime is required to perform an upgrade.

To upgrade Distribution, you will first need to verify the following.

Verify that you have upgraded Artifactory to v.7x. For more information, see Helm Upgrade.
f you are using the default PostgreSQL (postgresql.enabled=true), you need to pass previous 9.x or 10.x's postgresql.image.tag and databaseUpgradeReady=true; you will also need to delete the existing statefulset of the PostgreSQL subchart before the Helm upgrade because the 9.x chart version of PostgreSQL has breaking changes.
Run helm upgrade with the following values set.

```bash
       $ helm upgrade distribution --set databaseUpgradeReady=true --set unifiedUpgradeAllowed=true --set postgresql.postgresqlPassword=<old password> --set postgresql.image.tag=<old image tag> --set redis.password=<old password> --set distribution.joinKey=<JOIN_KEY> --set distribution.jfrogUrl=<ARTIFACTORY_URL> --set distribution.masterKey=<old master key> --set distribution.migration.enabled=true jfrog/distribution
```

Update the existing deployed version to the updated version.
```
helm upgrade distribution jfrog/distribution
```
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.
```
POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)
```
2. Upgrade the release by passing the previously auto-generated secret.
```
helm upgrade <myrelease> jfrog/Distribution --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}
```
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.
```
RABBITMQ_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-rabbitmq -o jsonpath="{.data.rabbitmq-password}" | base64 --decode)
```
2. Upgrade the release by passing the previously auto-generated secret.
```
helm upgrade <myrelease> jfrog/distribution --set rabbitmq.rabbitmqPassword=${RABBITMQ_PASSWORD}/rabbitmq-ha.rabbitmqPassword=${RABBITMQ_PASSWORD}
```
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.
```
helm upgrade --install distribution --namespace distribution jfrog/distribution --set rabbitmq-ha.rabbitmqPassword=<rabbit-password> --set postgresql.post
```

Migration Process

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

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

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

$ kubectl get svc
NAME                                        TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                       AGE
<OLD_RELEASE_NAME>-distribution              LoadBalancer   10.111.81.201    <pending>     80:31272/TCP                  50m
<OLD_RELEASE_NAME>-postgresql                ClusterIP      10.97.121.27      <none>       5432/TCP                      50m

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

$ OLD_PASSWORD=$(kubectl get secret -n <namespace> <OLD_RELEASE_NAME>-postgresql -o jsonpath="{.data.postgres-password}" | base64 --decode)

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.

$ helm install distribution-new --set replicaCount=0 --set distribution.jfrogUrl=<ARTIFACTORY_URL> --set postgresql.postgresqlPassword=<password> --set redis.password=<password> --set distribution.joinKey=<JOIN_KEY> jfrog/distribution

Connect to the new PostgreSQL pod (you can obtain the name by running kubectl get pods).
```
$ kubectl exec -it <NAME> bash
```
Once logged in, create a dump file from the previous database using pg_dump, and connect to the previous PostgreSQL chart.
```
$ pg_dump -h <OLD_PG_SERVICE_NAME> -U distribution <DATABASE_NAME> > /tmp/backup.sql
```
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.
Once you have the backup file, you can restore it with a command like the one below.
```
$ psql -U distribution <DATABASE_NAME> < /tmp/backup.sql
```
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.

Run the command helm upgradeto bring up Distribution.

#Example
$ helm upgrade --install distribution-new --set distribution.jfrogUrl=<ARTIFACTORY_URL> --set postgresql.postgresqlPassword=<password> --set redis.password=<password> --set distribution.joinKey=<JOIN_KEY> --set distribution.migration.enabled=true jfrog/distribution

Run the following command to remove the old Distribution deployment and Helm release.
```
helm delete <OLD_RELEASE_NAME>
```
Access Distribution from your browser at: http://<jfrogUrl>/ui/, then go to the Security & Compliance tab in the Application module in the UI.
Check the status of your deployed Helm releases.
```
helm status distribution
```
Distribution should now be ready for use.

Third Party Applications

PostgreSQL

If you have installed the PostgreSQL database packaged as part of 1.x, you can continue to use it. Use the following command to start and stop your PostgreSQL service.
Notice: the ./distribution.sh stop all command, used in Distribution 1.x versions cannot be used in version 2.x.

service postgresql-9.6 start|stop|status

Redis

This will be available from the previous install. Use the following commands to start and stop your service.

Red Hat / CentOS

service redis start|stop|status

Debian / Ubuntu

service redis-server start|stop|status

Content

Space Tools

Upgrading Distribution

Overview

Upgrade Steps

SELF-HOSTED

Upgrading from Version Below 1.6

Upgrading from Version 1.6 to 2.x

Interactive Script Upgrade (recommended)

Manual RPM Upgrade

Manual Debian Upgrade

Post-Upgrade Steps

Migrating Release Bundle Metadata to the Distribution Services

Upgrading from Version 2.x to 2.x

Interactive Script Upgrade (recommended)

Manual RPM/Debian Upgrade

Linux Archive Upgrade

Helm Upgrade

Migration Process

Third Party Applications

PostgreSQL

Redis