Upgrading Distribution to Version 1.4 and Below

Overview

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

The upgrade process consists of the following main steps:

Backing up your MongoDB collections and your $DISTRIBUTION_HOME folder as described in Before You Proceed.
Your next steps depend on whether you are running a single server installation or an HA cluster
1. Single Server Installation
  Run the upgrade script according to your installation type (Docker or Linux) as described in Running the Upgrade on a Single Node/Server.
2. HA Cluster
  Follow the instructions under Running the Upgrade on an HA Cluster. This process includes upgrading a single server installation for each node in the cluster.

Upgrading to Version 1.4

In version 1.4 JFrog Distribution underwent a significant change replacing its use of MongoDB with PostgreSQL. If you are upgrading to version 1.4, please pay close attention to the process of migrating your data from MongoDB to PostgreSQL as described in Migration Process.

Page Contents

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:

log example

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:
1. For each release bundle in the Release Bundles module, select the bundle to view its details.
2. For each version in the release bundle details, select the Distribution Tracking tab.
3. 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:
1. For a Docker installation run:
```
docker stop distribution_mongo_1
```
2. 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 .