Using the latest JFrog products?
JFrog Platform User Guide
JFrog Distribution 1.x Documentation
To get the latest version, go to the JFrog Unified Platform
Before You Proceed
Before you upgrade
We strongly recommend that you take the actions in this section to ensure you can roll back your system in case you encounter any issues during the upgrade process:
- Perform a full backup of the MongoDB collections.
- Backup the $DISTRIBUTION_HOME folder
Backing Up MongoDB Collections
How you backup your MongoDB collections depends on whether you are using Distribution's internal MongoDB database, or your organization's MongoDB database that is external to Distribution.
Backing up an internal MongoDB database
To backup Distribution's internal MongoDB database, follow these instructions:mongodump -h 127.0.0.01 -u distribution -p password -d distribution -o ./backup
Backing up an external MongoDB database
To back up your organization's external MongoDB database, please refer to mongodump in the mongoDB documentation.
Backing Up the Distribution Home Folder
Simply copy the contents of your $DISTRIBUTION_HOME folder to a backup folder of your choice.
Running the Upgrade on a Single Node/Server
Download the script from the JFrog Enterprise+ download page.
Upgrading on Docker
Using External Databases
JFrog Distribution uses a PostgreSQL database for different features of its operation, and gives you the option of installing a dedicated database instance during the installation process, or using your own PostgreSQL database if you already have one already installed and in use in your organization. If you have chosen to use your own PostgreSQL database, you need to ensure Distribution remains connected to it following an upgrade.
For more details, please refer to Using External Databases.
Perform a graceful shutdown of the Distribution server using the existing distribution.sh file:
Stop distribution./distribution stop
Run the
upgrade
command on the installation script using the new version of distribution.sh file:./distribution upgrade
- Make sure that the mongo server/docker container is up and running to make sure that the data migration can run.
Start Distribution using the new version of distribution.sh file. During the service initialization, the service first trigger the migration process.
./distribution start
Upgrading on Linux
Using External Databases
JFrog Distribution uses a PostgreSQL database for different features of its operation, and gives you the option of installing a dedicated database instance during the installation process, or using your own PostgreSQL database if you already have one already installed and in use in your organization. If you have chosen to use your own PostgreSQL database, you need to ensure Distribution remains connected to it following an upgrade.
For more details, please refer to Using External Databases.
Distribution is supported on a variety of flavors of Linux and follows standard conventions for folder structure. For details, please refer to Linux Installation.
The following instructions for upgrading Distribution are valid for all supported flavors of Linux.
To upgrade Distribution running on Linux, follow the instructions below replacing <linux-flavor> with the flavor you are using:
Extract the downloaded installation archive.
tar -xzf distribution-<linux-flavor>-latest.tar.gz
Run the installation script
(If you are not running as "root", prepend the following command with "sudo")../installDistribution-<linux-flavor>.sh
Migration Process
After you finish installing the new version while the upgraded node is booting, an automatic migration process is executed. This process makes the necessary changes to the configuration files and database tables.
This process may take some time depending on the database size.
You can track the migration process by looking in the Distribution server logs:
2018-08-06 09:49:13,589 [main] [INFO ] (o.j.b.d.a.l.ApplicationStartingListener:24) server version: 1.4.0, last database version was: 1.3.0 2018-08-06 09:52:13,285 [main] [INFO ] (o.j.b.d.a.b.m.AbstractMigrationService:31) running migration from 1.3.0 to 1.4.0 .... 2018-08-06 09:53:21,276 [main] [INFO ] (o.j.b.d.a.l.ApplicationStartedListener:27) server version: 1.4.0, last configuration version was: 1.3.0 2018-08-06 09:53:22,674 [main] [INFO ] (o.j.b.d.a.b.m.AbstractMigrationService:31) running migration from 1.3.0 to 1.4.0 .... 2018-08-06 09:53:42,111 [main] [INFO ] (o.j.b.d.a.b.m.DataBaseMigrationService:79) Migration to 1.4.0 finished successfully. time took to complete: 20 seconds
Running the Upgrade on an HA Cluster
Distribution HA is available from Distribution version 1.2.
Down time required
In the current version upgrade full down time is required in order to successfully migrate the data from mongoDb to PostgreSQL
Upgrade should be executed one node at a time
When upgrading an HA cluster, make sure complete the upgrade process on one node at a time before moving on to the next one.
Make sure that there are no distribution processes that are in progress or about to start as follows:
For each release bundle in the Release Bundles module, select the bundle to view its details.
For each version in the release bundle details, select the Distribution Tracking tab.
For each distribution process, verify that its status is either Completed, Failed or Aborted
Stop all JFrog Distribution processes servers
Upgrade each node in the cluster as described in Running the Upgrade on a Single Node/Server.
- After all nodes were upgraded and successfully started you may shutdown the mongoDB database as it is no longer used:
For a Docker installation run:
docker stop distribution_mongo_1
For a native installation run:
service mongod stop
Recovering from Upgrade Failure
If for some reason the migration process fails and you see exceptions in the server log or the server does not start after migration, you may need to revert to the previous version and contact our support for assistance.
Before reverting to a previous version
Before reverting to a previous version, please save the distribution.log
and run a dump
on Distribution's postgreSQL database to help us investigate and fix the issue.
To revert to the previous version, follow these steps:
- Perform a fresh install of the previous version of Distribution. For details, please refer to Installing Distribution.
Before starting the server, restore the Mongo collection from the backup you created using
mongorestore
. For more details, please refer to mongorestore in the MongoDB documentation.- Copy $DISTRIBUTION_HOME from the backup you created to its original location.
Delete all tables that may have been created in the PostgreSQL database.
- Start the server.
Upgrading from Any Version Below Distribution 1.2
To upgrade from any version below version 1.2 (for example, 1.1), follow the these steps:
- Stop the Distribution server.
Drop the Mongo database used by the distribution (usually called "distribution") by using '
db.dropDatabase()'. For more information, see db.dropDatabase.
- Delete the content of $DISTRIBUTION_HOME folder
- Install ther new version by following the Installing Distribution Instructions.
- Reconfigure distribution according to the configuration from the previous version.
- Recreate the release bundles and permissions from the previous version.
Deploying your GPG Key on the source Artifactory
Starting from v1.3.0, Distribution will trigger the source Artifactory to clone the contents of the signed release bundle into an isolated release-bundles repository. To allow this, you will need to deploy your GPG Key, that is used in each of your Artifactory Edge nodes, to the source Artifactory. Refer to the JFrog Artifactory User Guide.