Upgrading from Distribution Version 1.6 to 2.x

JFrog Installation & Setup Documentation
Content Type
Installation & Setup
ft:sourceType
Paligo

Warning

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.JFrog Self-Hosted Overview

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.

  1. Download Distribution

  2. Stop the service.

    Docker - Stop and remove old containers Linux

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

    .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.

  4. 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 RPM/DEB

  5. 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.

  6. Start and manage the Distribution service.

    systemd OS systemv OS Docker Compose

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

  8. Check Distribution Log.

    Linux

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.

  1. Download Distribution.

  2. Stop the current server.

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

  4. Install Distribution as a service on Red Hat compatible Linux distributions, as a root user.

  5. 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.

  6. 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.keyused by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

  7. Make sure the third party services are running.

    Note

    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.

    Note

    Redis

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

    Red Hat / CentOS Debian / Ubuntu

  8. Start and manage Distribution.

    systemd OS systemv OS

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

  10. Check the Distribution 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.

  1. Download Distribution.

  2. Stop the current server.

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

  4. Install Distribution as a service on a Debian compatible Linux distributions, as a root user.

    Run Installation

  5. 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.

  6. 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.keyused by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/distribution/var/etc/system.yaml file.

  7. Make sure the third party services are running.

    Note

    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.

    Note

    Redis

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

    Red Hat / CentOS Debian / Ubuntu

  8. Start and manage Distribution.

    systemd OS systemv OS

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

  10. Check the Distribution Log.

  11. Start and manage Distribution.

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

  13. Check the Distribution 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.