Upgrading Distribution

Overview

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

Upgrading from a version below 1.4 to version 1.4 and above

In version 1.4 JFrog Distribution underwent a significant change replacing its use of MongoDB with PostgreSQL. As a result, if your current version is below 1.4 and you are upgrading to version 1.4 and above you must first upgrade to version 1.4 as described in Upgrading Distribution to Version 1.4 and Below. Then, if you wish to continue upgrading to a newer version, follow the instructions on this page

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.

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 your DB
Backup the $DISTRIBUTION_HOME folder

Backing Up PostgreSQL DB

How you backup your PostgreSQL DB depends on whether you are using Distribution's internal database, or your organization's database that is external to Distribution.

Backing up an internal PostgreSQL DB
To backup Distribution's internal PostgreSQL database, follow these instructions:
```
pg_dump -f <backupFile> distributiondb
```
Backing up an external database
To back up your organization's database, please refer to postgresdump in the PostgreSQL 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 distribution.sh file of your current version:
Stop distribution
```
./distribution stop
```
Run the upgrade command on the distribution.sh installation script of the new version you are upgrading to:
```
./distribution upgrade
```
Make sure that the PostgreSQL server/docker container is up and running to make sure that the data migration can run.
Start Distribution using the distribution.sh installation script of the new version you are upgrading to. During the service initialization, the service first triggers 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 Installing on Linux.

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 up, 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

2019-02-21 13:21:56,921 [main] [INFO ] (o.j.b.d.a.l.ApplicationContextReadyListener:33) server version: 1.6.0, last database version was: 1.5.1
2019-02-21 13:21:57,000 [main] [INFO ] (o.j.b.d.a.b.m.AbstractMigrationService:31) running migration from 1.5.1 to 1.6.0
2019-02-21 13:21:57,010 [main] [INFO ] (o.j.b.d.s.d.DataBaseSchemaServiceImpl:184) Index created: edge_artifact_tracker_idx in table: edge_node_tracker_artifact
2019-02-21 13:21:57,052 [main] [INFO ] (o.j.b.d.s.d.DataBaseSchemaServiceImpl:130) Created table: metric_audit
2019-02-21 13:21:57,058 [main] [INFO ] (o.j.b.d.s.d.DataBaseSchemaServiceImpl:184) Index created: rb_dist_audit_edge_tracker_idx in table: rb_dist_audit
2019-02-21 13:21:57,086 [main] [INFO ] (o.j.b.d.s.d.DataBaseSchemaServiceImpl:112) Created table: call_home
2019-02-21 13:21:57,111 [main] [INFO ] (o.j.b.d.a.b.m.d.DataBaseMigrationService:105) Migration to 1.6.0 finished successfully. time took to complete: 0 seconds

Running the Upgrade on an HA Cluster

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 ongoing distributions 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
Upgrade each node in the cluster as described in Running the Upgrade on a Single Node/Server.

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 PostgreSQL database from the backup you created using:
posgresql-restore
```
pg_restore -f <backupFile> -d distributiondb
```
For more details, please refer to app-pgrestorein the PostgreSQL documentation.
Copy $DISTRIBUTION_HOME from the backup you created to its original location.
Start the server.