Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

This page describes the process to upgrade your Artifactory Enterprise HA cluster.   

No down time

 Since your cluster contains more than one node, you may complete the upgrade process without incurring any down time to the Artifactory service your organization is using.

Before You Begin

  1. Backup your system: As a precaution, before you begin the upgrade process, we strongly recommend performing a complete Complete System Backup
  2. Read through the process: The backup procedure may vary slightly depending on your current version and your installation type (ZIP, RPM, Debian or Docker). To familiarize yourself with the specific backup process that you should use, we recommend reading through all the steps of the process before you begin.
Page Contents

 

 


The Upgrade Process

Upgrading Artifactory HA depends on which version you are starting from. Read the sections below carefully to make sure you complete the process correctly. 

Upgrading to 5.x for the first time? NFS is no longer required

From version 5.0, Artifactory HA does not require a network file system (NFS) to store data. If you wish to migrate your filestore to alternative storage locations, please refer to Migrating Data from NFS.

Upgrading from Version 4.x or 5.x

Upgrading to the latest version is conducted in three phases:
  1. Upgrading the primary node
  2. Upgrading the secondary nodes
  3. Verifying the HA installation and configuration

 

Want to stop using NFS?

If you want to stop using a shared NFS once the upgrade procedure is complete (this is optional), please refer to Migrating Data from NFS to migrate to alternative storage.

Upgrading the Primary Node

  1. Remove the primary node from the load balancer, so all requests are directed to the secondary nodes. You may look at  $ARTIFACTORY_NODE_HOME/logs/request.log and ARTIFACTORY_URL/api/tasks (search for "running") to ensure that Artifactory is completely inactive.
  2. Perform a graceful shutdown of the primary node. While the primary node is down, the load balancer should redirect all queries to the secondary nodes.
  3. Continue with the upgrade according to the instructions for your installation type.

    Upgrading from 3.x?

     If your current version is 3.5 or higher, you first need to upgrade to the latest version 4.x using the procedure in this link and then upgrade to 5.x.

    Upgrading Artifactory HA from a version below 3.5 to version 5.x directly is not supported. To upgrade to version 5.x, you first need to upgrade your system to v3.5+, and then upgrade again to the final version 4.x, and then finally to 5.x.

    ZIP Installation

     Upgrading a ZIP installation...
    1. Unzip the Artifactory distribution archive.
    2. If the $ARTIFACTORY_HOME/tomcat/conf/server.xml has been modified keep it in a temporary location.  
    3. Backup files to a temporary location according to the conditions described below:
      1. In all cases, backup $ARTIFACTORY_HOME/bin/artifactory.default
      2. If Artifactory is configured to work with a database that is not Derby, backup the $ARTIFACTORY_HOME/tomcat/lib/<JDBC> driver.  
    4. Remove the following files and folders from your $ARTIFACTORY_HOME folder:
      • webapps/artifactory.war

      • webapps/access.war

      • tomcat
      • bin

    5. Replace the removed files and folders with the corresponding ones from the new unzipped version.
    6. Any files that were stored in temporary locations should now be returned to their original location under the new installation.
    7. If you installed Artifactory as a service, you now need to run the service
      1. For a Linux service, browse to $ARTIFACTORY_HOME/bin and execute the following command as root: $ARTIFACTORY_HOME/bin/installService.sh [USER [GROUP]]

      2. For  Windows service, browse to %ARTIFACTORY_HOME%\bin and run InstallService.bat

    misc Folder

     The misc folder contains configuration files for specialized environments such as when running Artifactory as a Standalone Installation or on IBM Websphere (which was supported for versions of Artifactory below 4.0).

    Although these files are not required for runtime, it is recommended to replace this folder too.

    Debian Installation

     Upgrading a Debian installation...
    1. Log in as root (or use sudo su -).
    2. Execute the following command:

      dpkg -i $jfrog-artifactory-<oss|pro>-5.y.z.deb
    Managing Configuration Files

    When upgrading a Debian installation the upgrade process overwrites the following set of configuration files:

    • system.properties
    • config.xml
    • default
    • logback.xml
    • mimetypes.xml
    • All files under opt/jfrog/artifactory/misc
    • All files under opt/jfrog/artifactory/webapps

    If any of these files were modified, a backed up file will be created automatically with a notification in the upgrade log. If you need to restore the configuration changes you can restore them from the backup created.

    Docker Installation 

     Upgrading a Docker installation...

    In order to keep your data and configuration between versions, when upgrading the Artifactory Docker image, you need to use an external mounted volume as described under Managing Data Persistence.

    To upgrade the Artifactory Docker image, follow these steps:

    1. Stop current container
    2. Start a container with new version, using same data and configuration
    3. Remove old container

    The example below shows this process for upgrading Artifactory from v5.0.0 to v5.1.0.

    $ # Stop the currently running container
    $ docker stop artifactory-5.0.0
     
    $ # Start a new container from the new version image
    $ docker run -d --name artifactory-5.1.0 --volumes-from=artifactory-5.0.0 -p 8081:8081 docker.bintray.io/jfrog/artifactory-pro:5.1.0
     
    $ # Remove old container
    $ docker rm artifactory-5.0.0

    Once these commands have completed successfully, you would have the new version (5.1.0 in the above example) running with the data and configuration from the old version that was removed.

    RPM Installation

     Upgrading an RPM installation...

    Make sure you are upgrading from v3.6 or above

    When running as an RPM installation, you can only upgrade to v5.x if your current version is 3.6 or above. If necessary, first upgrade your current version to 3.6, and then upgrade to v5.x .

    If you try to upgrade a version below 3.6 using rpm --force you may end up deleting all of your data.

    1. Download the Artifactory Pro RPM Installer. The latest version can be downloaded from the JFrog Artifactory Pro Download Page. Previous versions can be downloaded from JFrog Bintray.
    2. Log in as root (or use sudo su -).
    3. Execute the following command:

      rpm -U jfrog-artifactory-pro-5.y.z.rpm

      Switching from Artifactory OSS to Pro

      If you are just switching from Artifactory OSS to Pro with the same version number, you need to append the command with --force --nodeps as follows:
      rpm -U jfrog-artifactory-pro-5.y.z.rpm --force --nodeps

    During an upgrade of an RPM installation different files may get backed up, where the backup file is appended with either a .rpmorig or a .rpmnew extension. 

    .rpmorig extension means that the original file in your installation, the one that was there before performing the upgrade, was backed up before being replaced in the upgrade process.

    .rpmnew extension means that the original file in your installation, was not replaced in the upgrade, and instead, the new file with the same filename was backed up.

    In either case, Artifactory will display a message such as:

    warning: /etc/opt/jfrog/artifactory/default saved as /etc/opt/jfrog/artifactory/default.rpmorig

    In these cases we recommend comparing the file installed once the upgrade has been completed with the backed-up file to see which best fits your needs, and using that one in the final setup.

    If you make any changes, you may need to restart Artifactory for the change to be applied.

    Upgrading Using YUM

    An easy way to upgrade Artifactory from version 3.x  or 4.x to the latest version is to use YUM with the Bintray Artifactory repository. The code snippets below show how to do this depending on whether your current version is below 3.6, or 3.6 and above.

     If your current version is 3.6 and above:
    curl https://bintray.com/jfrog/artifactory-pro-rpms/rpm -o bintray-jfrog-artifactory-pro-rpms.repo && sudo mv bintray-jfrog-artifactory-pro-rpms.repo /etc/yum.repos.d
    yum install jfrog-artifactory-pro
     If your current version is below 3.6:
    curl https://bintray.com/jfrog/artifactory-pro-rpms/rpm -o bintray-jfrog-artifactory-pro-rpms.repo && sudo mv bintray-jfrog-artifactory-pro-rpms.repo /etc/yum.repos.d
    yum upgrade artifactory 
    yum install jfrog-artifactory-pro

  4. Start up the primary node. When the primary node starts up, it will recognize that the HA cluster nodes are not all running the same version of Artifactory, and consequently, the system will be limited to allowing uploads and downloads. 

    Any attempt to perform other actions such as changing the DB schema, modifying permissions, changing repository configuration and more, are strictly blocked. This limitation will continue until all the cluster nodes are once again running the same version.

    Version inconsistency generates exceptions

    Running the HA cluster nodes with different versions generates exceptions. These can be seen in the log files and reflect the temporary inconsistent state during the upgrade process. This is normal and should be ignored until all the cluster nodes are, once again, running the same version.

  5. Put the primary node back to the load balancer.

Upgrading the Secondary Node

For each secondary node in your HA cluster, perform the following steps:

  1. Remove the node from the load balancer, so all requests are directed to the other nodes. You may look at  $ARTIFACTORY_NODE_HOME/logs/request.log and ARTIFACTORY_URL/api/tasks (search for "running") to ensure that Artifactory is completely inactive.
  2. Perform a graceful shutdown of the node. While the node is down, the load balancer should redirect all queries to the other nodes.

  3. Continue with the upgrade according to the instructions for your installation type.

    If your current version is 3.5 or higher, you first need to upgrade to the latest version 4.x using the following procedure and then upgrade to 5.x.

    Upgrading Artifactory HA from a version below 3.5 to version 5.x directly is not supported. To upgrade to version 5.x, you first need to upgrade your system to v3.5+, and then upgrade again to the final version 4.x, and then finally to 5.x.

    ZIP Installation

     Upgrading a ZIP installation...
    1. Unzip the Artifactory distribution archive.
    2. If the $ARTIFACTORY_HOME/tomcat/conf/server.xml has been modified keep it in a temporary location.  
    3. Backup files to a temporary location according to the conditions described below:
      1. In all cases, backup $ARTIFACTORY_HOME/bin/artifactory.default
      2. If Artifactory is configured to work with a database that is not Derby, backup the $ARTIFACTORY_HOME/tomcat/lib/<JDBC> driver.  
    4. Remove the following files and folders from your $ARTIFACTORY_HOME folder:
      • webapps/artifactory.war

      • webapps/access.war

      • tomcat
      • bin

    5. Replace the removed files and folders with the corresponding ones from the new unzipped version.
    6. Any files that were stored in temporary locations should now be returned to their original location under the new installation.
    7. If you installed Artifactory as a service, you now need to run the service
      1. For a Linux service, browse to $ARTIFACTORY_HOME/bin and execute the following command as root: $ARTIFACTORY_HOME/bin/installService.sh [USER [GROUP]]

      2. For  Windows service, browse to %ARTIFACTORY_HOME%\bin and run InstallService.bat

    misc Folder

     The misc folder contains configuration files for specialized environments such as when running Artifactory as a Standalone Installation or on IBM Websphere (which was supported for versions of Artifactory below 4.0).

    Although these files are not required for runtime, it is recommended to replace this folder too.

    Debian Installation

     Upgrading a Debian installation...
    1. Log in as root (or use sudo su -).
    2. Execute the following command:

      dpkg -i $jfrog-artifactory-<oss|pro>-5.y.z.deb
    Managing Configuration Files

    When upgrading a Debian installation the upgrade process overwrites the following set of configuration files:

    • system.properties
    • config.xml
    • default
    • logback.xml
    • mimetypes.xml
    • All files under opt/jfrog/artifactory/misc
    • All files under opt/jfrog/artifactory/webapps

    If any of these files were modified, a backed up file will be created automatically with a notification in the upgrade log. If you need to restore the configuration changes you can restore them from the backup created.

    Docker Installation 

     Upgrading a Docker installation...

    In order to keep your data and configuration between versions, when upgrading the Artifactory Docker image, you need to use an external mounted volume as described under Managing Data Persistence.

    To upgrade the Artifactory Docker image, follow these steps:

    1. Stop current container
    2. Start a container with new version, using same data and configuration
    3. Remove old container

    The example below shows this process for upgrading Artifactory from v5.0.0 to v5.1.0.

    $ # Stop the currently running container
    $ docker stop artifactory-5.0.0
     
    $ # Start a new container from the new version image
    $ docker run -d --name artifactory-5.1.0 --volumes-from=artifactory-5.0.0 -p 8081:8081 docker.bintray.io/jfrog/artifactory-pro:5.1.0
     
    $ # Remove old container
    $ docker rm artifactory-5.0.0

    Once these commands have completed successfully, you would have the new version (5.1.0 in the above example) running with the data and configuration from the old version that was removed.

    RPM Installation

     Upgrading an RPM installation...

    Make sure you are upgrading from v3.6 or above

    When running as an RPM installation, you can only upgrade to v5.x if your current version is 3.6 or above. If necessary, first upgrade your current version to 3.6, and then upgrade to v5.x .

    If you try to upgrade a version below 3.6 using rpm --force you may end up deleting all of your data.

    1. Download the Artifactory Pro RPM Installer. The latest version can be downloaded from the JFrog Artifactory Pro Download Page. Previous versions can be downloaded from JFrog Bintray.
    2. Log in as root (or use sudo su -).
    3. Execute the following command:

      rpm -U jfrog-artifactory-pro-5.y.z.rpm

      Switching from Artifactory OSS to Pro

      If you are just switching from Artifactory OSS to Pro with the same version number, you need to append the command with --force --nodeps as follows:
      rpm -U jfrog-artifactory-pro-5.y.z.rpm --force --nodeps

    During an upgrade of an RPM installation different files may get backed up, where the backup file is appended with either a .rpmorig or a .rpmnew extension. 

    .rpmorig extension means that the original file in your installation, the one that was there before performing the upgrade, was backed up before being replaced in the upgrade process.

    .rpmnew extension means that the original file in your installation, was not replaced in the upgrade, and instead, the new file with the same filename was backed up.

    In either case, Artifactory will display a message such as:

    warning: /etc/opt/jfrog/artifactory/default saved as /etc/opt/jfrog/artifactory/default.rpmorig

    In these cases we recommend comparing the file installed once the upgrade has been completed with the backed-up file to see which best fits your needs, and using that one in the final setup.

    If you make any changes, you may need to restart Artifactory for the change to be applied.

    Upgrading Using YUM

    An easy way to upgrade Artifactory from version 3.x  or 4.x to the latest version is to use YUM with the Bintray Artifactory repository. The code snippets below show how to do this depending on whether your current version is below 3.6, or 3.6 and above.

     If your current version is 3.6 and above:
    curl https://bintray.com/jfrog/artifactory-pro-rpms/rpm -o bintray-jfrog-artifactory-pro-rpms.repo && sudo mv bintray-jfrog-artifactory-pro-rpms.repo /etc/yum.repos.d
    yum install jfrog-artifactory-pro
     If your current version is below 3.6:
    curl https://bintray.com/jfrog/artifactory-pro-rpms/rpm -o bintray-jfrog-artifactory-pro-rpms.repo && sudo mv bintray-jfrog-artifactory-pro-rpms.repo /etc/yum.repos.d
    yum upgrade artifactory 
    yum install jfrog-artifactory-pro

  4. Start up the secondary node.
  5. Add the secondary node back to the load balancer.
  6. Repeat this process for each secondary node.

Check your installation

 After starting up each secondary node, we recommend inspecting the ha-node.properties, db.properties and binarystore.xml files (under $ARTIFACTORY_NODE_HOME/etc) to ensure they are correctly configured 

Verify the HA Installation and Configuration

Once you have completed upgrading your HA cluster, you can verify that your cluster has been installed and configured correctly use the following series of tests:

  1. Directly Access the Artifactory UI for the server you have just configured
  2. In the Admin module go to Advanced | System Logs to view the log and verify that you see an entry for HA Node ID.
    Artifactory HA Log File
  3. The bottom of the module navigation bar should also indicate that you are running with an Enterprise licens. In case of an error you will see an error message in the page header.
  4. Access Artifactory through your load balancer and log in as Admin.
  5. In the Admin module go to Configuration.  There should be a section called High Availability. When selected you should see a table with details on all the Artifactory nodes in your cluster as displayed below.

    HA Cluster Nodes

  6. In the Admin module under Configuration | General, verify that the Custom URL Base field is correctly configured to the URL of the Load Balancer.

 

Want to stop using NFS?

If you want to stop using a shared NFS once the upgrade procedure is complete (this is optional), please refer to Migrating Data from NFS to migrate to alternative storage.

 

 

 

 

 

 

 

 

  • No labels