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 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 containersdistribution stop docker ps -a --format '{{.Names}}' | grep ^distribution_* | xargs docker rm -f
Linuxcd /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:
migration log:
$JFROG_HOME/distribution/var/log/migration.log
file.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 OSsystemctl start|stop distribution.service
systemv OSservice distribution start|stop
Docker Composecd 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.
Linuxtail -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:
migration log:
$JFROG_HOME/distribution/var/log/migration.log
file.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 ArtifactoryjoinKey
(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.
- 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"
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 / CentOSservice redis start|stop|status
Debian / Ubuntuservice redis-server start|stop|status
Start and manage Distribution.
systemd OSsystemctl start|stop distribution.service
systemv OSservice 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 Installationdpkg -i ./distribution/distribution.deb
Check that the migration has completed successfully, by reviewing the following files:
migration log:
$JFROG_HOME/distribution/var/log/migration.log
file.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 ArtifactoryjoinKey
(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.
- 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"
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 / CentOSservice redis start|stop|status
Debian / Ubuntuservice redis-server start|stop|status
Start and manage Distribution.
systemd OSsystemctl start|stop distribution.service
systemv OSservice 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 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 OSsystemctl stop distribution.service
Systemv OSservice distribution stop
Docker - Stop and remove old containerscd 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 currentdocker-compose.yaml
file to the new extracted version of thedocker-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 thejfrogURL
(custom base URL) andjoinKey
.Compose./config.sh
RPM/DEB./install.sh
Start and manage the Distribution service.
systemd OSsystemctl start|stop
distribution.service
systemv OSservice distribution start|stop
Docker Composecd 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 OSsystemctl stop distribution.service
systemv OSsservice 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.
rpmyum -y install ./distribution/distribution.rpm
Debiandpkg -i ./distribution/distribution.deb
Start and manage Distribution.
systemd OSsystemctl start|stop distribution.service
systemv OSservice 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.
Untarmv 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.
Upgradeexport 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 theredis.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'spostgresql.image.tag
anddatabaseUpgradeReady=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.
Runhelm 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.Get the current password by running the following.
POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)
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.Get the current password by running the following.
RABBITMQ_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-rabbitmq -o jsonpath="{.data.rabbitmq-password}" | base64 --decode)
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.
- Retrieve all current passwords (RabbitMQ/PostgreSQL) as explained in the above section.
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 upgrade
to 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.
service redis start|stop|status
service redis-server start|stop|status