Upgrading an Enterprise HA Cluster

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 From Versions Below 5.4.6

Upgrading Steps

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 you have not yet done so, perform a graceful shutdown of your currently running installation.

   3. If the $ARTIFACTORY_HOME/tomcat/conf/server.xml has been modified keep it in a temporary location.  

   4. 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.  
   5. Remove the following files and folders from your $ARTIFACTORY_HOME folder:
      

      • webapps/artifactory.war

      • webapps/access.war (this will only be present if your current version is 5.4.0 and above due to addition of the Access Service)

      • tomcat

      • bin

      • misc

   6. Replace the removed files and folders with the corresponding ones from the new unzipped version.

   7. Any files that were stored in temporary locations should now be returned to their original location under the new installation.

      Running Artifactory as a ROOT application in Tomcat

      If you have configured Artifactory to run as the ROOT application in Tomcat, before you proceed, you need to follow the steps described in this Knowledge Base article.

      Version-specific Special Instructions

      To accommodate internal changes in Artifactory in different version upgrades, you need to perform or ensure certain changes to Artifactory's server.xml according to your target upgrade version. Note that the changes listed below are cumulative as the versions progress.

      Upgrading to version 5.4.0 and above

      From version 5.4.0, Artifactory's management of Access Tokens was moved to a separate service, JFrog Access, installed as a separate web application under the same Tomcat as Artifactory. This requires your Tomcat's server.xml to be configured to allow running 2 processes. If you are using a server.xml file from a previous installation, when returning it, make sure it is configured to allow 2 start/stop threads as shown below (see <Host name="localhost" appBase="webapps" startStopThreads="2"/>):

      ...
              <Engine name="Catalina" defaultHost="localhost">
                  <Host name="localhost" appBase="webapps" startStopThreads="2"/>
              </Engine>
      ...

      Upgrading to version 5.6.1 and above

      In version 5.6.1, the version of the Tomcat embedded in Artifactory was upgraded. To accommodate YUM clients following this upgrade, a new attribute, sendReasonPhrase was added for each Tomcat connector in the server.xml file as shown in the example below:

      <Connector port="8081" sendReasonPhrase="true"/>

      Upgrading to version 5.7.0 and above

      From version 5.7.0, Artifactory routes requests to its Access service directly through a port, and this requires the following modification to the server.xml file

      <Connector port="8040" sendReasonPhrase="true" maxThreads="50"/>

      Upgrading to version 6.3 and above

      From version 6.3, the version of the Tomcat embedded in Artifactory was upgraded. To accommodate special characters following this upgrade, the following new attributes, relaxedPathChars='[]' relaxedQueryChars='[]' were added for each Tomcat connector in the server.xml as shown in the example below:

      
      

        <Service name="Catalina">
              <Connector port="8081" sendReasonPhrase="true" relaxedPathChars='[]' relaxedQueryChars='[]'/>

   8. 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. First uninstall the service by running uninstallService.bat, then reinstall the service by running installService.bat. You can now run the service through the Windows UI or as described in Running Artifactory.

   Debian Installation

    Upgrading a Debian installation...

   1. Log in as root (or use sudo su -).
   2. If you have not yet done so, perform a graceful shutdown of your currently running installation

   3. Execute the following command:

      dpkg -i $jfrog-artifactory-<oss|pro>-6.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.

   Running Artifactory as ROOT

   If you have configured Artifactory to run as the ROOT application in Tomcat, before you proceed, you need to follow the steps described in this Knowledge Base article.

   Version-specific Special Instructions

   To accommodate internal changes in Artifactory in different version upgrades, you need to perform or ensure certain changes to Artifactory's server.xml according to your target upgrade version. Note that the changes listed below are cumulative as the versions progress.

   Upgrading  to version 5.4.0 and above

   From version 5.4.0, Artifactory's management of Access Tokens was moved to a separate service, JFrog Access, installed as a separate web application under the same Tomcat as Artifactory. This requires your Tomcat's server.xml to be configured to allow running 2 processes. If you are using a server.xml file from a previous installation, when returning it, make sure it is configured to allow 2 start/stop threads as shown below (see <Host name="localhost" appBase="webapps" startStopThreads="2"/>):

   ...
           <Engine name="Catalina" defaultHost="localhost">
               <Host name="localhost" appBase="webapps" startStopThreads="2"/>
           </Engine>
   ...

   Upgrading to version 5.6.1 and above

   In version 5.6.1, the version of the Tomcat embedded in Artifactory was upgraded. To accommodate YUM clients following this upgrade, a new attribute, sendReasonPhrase was added for each Tomcat connector in the server.xml file as shown in the example below:

   <Connector port="8081" sendReasonPhrase="true"/>

   Upgrading to version 5.7.0 and above

   From version 5.7.0, Artifactory routes requests to its Access service directly through a port, and this requires the following modification to the server.xml file

   <Connector port="8040" sendReasonPhrase="true" maxThreads="50"/>

   Upgrading to version 6.3 and above

   From version 6.3, the version of the Tomcat embedded in Artifactory was upg

     <Service name="Catalina">
           <Connector port="8081" sendReasonPhrase="true" relaxedPathChars='[]' relaxedQueryChars='[]'/>

    Upgrading Debian OSS to Pro

   To ensure that all of the data remains in Artifactory following the upgrade to Pro (assuming you are using the default DB), please follow these steps:

   1. Perform a graceful shutdown of your currently running installation.
      
   2. Perform a backup of $ARTIFACTORY_HOME/data folder.
      
      

   3. Delete the OSS installation.

      apt-get remove jfrog-artifactory-oss)

   4. Download and install the Pro package.

      dpkg -i $jfrog-artifactory-pro-<version>.deb)

   5. Import the ‘data’ backup folder to the new installation location.

      $ARTIFACTORY_HOME/data

   6. Start Artifactory.

      $ARTIFACTORY_HOME/data

   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 the current container
   2. Start a container with the new version using same data and configuration
   3. Remove the 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.

   Running Artifactory as ROOT

   If you have configured Artifactory to run as the ROOT application in Tomcat, you need to follow the steps described in this Knowledge Base article.

   Version-specific Special Instructions

   To accommodate internal changes in Artifactory in different version upgrades, you need to perform or ensure certain changes to Artifactory's server.xml according to your target upgrade version. Note that the changes listed below are cumulative as the versions progress.

   Upgrading  to version 5.4.0 and above

   From version 5.4.0, Artifactory's management of Access Tokens was moved to a separate service, JFrog Access, installed as a separate web application under the same Tomcat as Artifactory. This requires your Tomcat's server.xml to be configured to allow running 2 processes. If you are using a server.xml file from a previous installation, when returning it, make sure it is configured to allow 2 start/stop threads as shown below (see <Host name="localhost" appBase="webapps" startStopThreads="2"/>):

   ...
           <Engine name="Catalina" defaultHost="localhost">
               <Host name="localhost" appBase="webapps" startStopThreads="2"/>
           </Engine>
   ...

   Upgrading to version 5.6.1 and above

   In version 5.6.1, the version of the Tomcat embedded in Artifactory was upgraded. To accommodate YUM clients following this upgrade, a new attribute, sendReasonPhrase was added for each Tomcat connector in the server.xml file as shown in the example below:

   <Connector port="8081" sendReasonPhrase="true"/>

   Upgrading to version 5.7.0 and above

   From version 5.7.0, Artifactory routes requests to its Access service directly through a port, and this requires the following modification to the server.xml file

   <Connector port="8040" sendReasonPhrase="true" maxThreads="50"/>

   Upgrading from version 6.3 and above

   From version 6.3, the version of the Tomcat embedded in Artifactory was upgraded. To accomodate special characters following this upgrade, the following new attributes, relaxedPathChars='[]' relaxedQueryChars='[]' were added for each Tomcat connector in the server.xml as shown in the example below:

    <Service name="Catalina">
           <Connector port="8081" sendReasonPhrase="true" relaxedPathChars='[]' relaxedQueryChars='[]'/>

   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. If you have not yet done so, perform a graceful shutdown of your currently running installation

   4. Execute the following command:

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

      Switching from Artifactory OSS to Pro

      If you are just switching from Artifactory  with the same version number, you need to append the command with --force --nodeps as follows:

      rpm -U jfrog-artifactory-pro-6.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. 

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

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

   Upgrading an Artifactory HA cluster?

    If you are upgrading an Artifactory HA cluster, and you are running with a version that is older than version 5.4.6, you should review the instructions on Upgrading an Enterprise HA Cluster prior to upgrading.

    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-6.y.z

   To install the latest version of Artifactory, you can run:

   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-6.y.z

   To install the latest version of Artifactory, you can run:

   yum install jfrog-artifactory-pro

   Running Artifactory as ROOT

   If you have configured Artifactory to run as the ROOT application in Tomcat, before you proceed, you need to follow the steps described in this Knowledge Base article.

   Version-specific Special Instructions

   To accommodate internal changes in Artifactory in different version upgrades, you need to perform or ensure certain changes to Artifactory's server.xml according to your target upgrade version. Note that the changes listed below are cumulative as the versions progress.
   
   

   Upgrading  to version 5.4.0 and above

   From version 5.4.0, Artifactory's management of Access Tokens was moved to a separate service, JFrog Access, installed as a separate web application under the same Tomcat as Artifactory. This requires your Tomcat's server.xml to be configured to allow running 2 processes. If you are using a server.xml file from a previous installation, when returning it, make sure it is configured to allow 2 start/stop threads as shown below (see <Host name="localhost" appBase="webapps" startStopThreads="2"/>):

   ...
           <Engine name="Catalina" defaultHost="localhost">
               <Host name="localhost" appBase="webapps" startStopThreads="2"/>
           </Engine>
   ...

   Upgrading to version 5.6.1 and above

   In version 5.6.1, the version of the Tomcat embedded in Artifactory was upgraded. To accommodate YUM clients following this upgrade, a new attribute, sendReasonPhrase was added for each Tomcat connector in the server.xml file as shown in the example below:

   <Connector port="8081" sendReasonPhrase="true"/>

   Upgrading to version 5.7.0 and above

   From version 5.7.0, Artifactory routes requests to its Access service directly through a port, and this requires the following modification to the server.xml file

   <Connector port="8040" sendReasonPhrase="true" maxThreads="50"/>

   Upgrading from version 6.3 and above
   
   From version 6.3, the version of the Tomcat embedded in Artifactory was upgraded. To accomodate special characters following this upgrade, the following new attributes, relaxedPathChars='[]' relaxedQueryChars='[]' were added for each Tomcat connector in the server.xml as shown in the example below:

    <Service name="Catalina">
           <Connector port="8081" sendReasonPhrase="true" relaxedPathChars='[]' relaxedQueryChars='[]'/>

4. Complete this step only when upgrading from 5.4.5 and below to 5.7 and above with 'One phase with downtime'
   Copy the Master Key from the primary node located under the $ARTIFACTORY_HOME/etc/security/master.key directory, to the secondary node under the $ARTIFACTORY_HOME/etc/security/master.key directory.
5. Start up the secondary node.
6. Add the secondary node back to the load balancer.

7. Repeat this process for each secondary node.

    

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.
   
3. The bottom of the module navigation bar should also indicate that you are running with an Enterprise license. 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.

   

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.

Troubleshooting

Recovering from an Attempt to Upgrade Directly to Version 5.5 and Above

If you try to upgrade from version 5.4.5 and below to version 5.5 and above without following the procedure in one of the two options above, the upgrade will fail with the following message:

To upgrade your HA installation to this version, you first need to upgrade to version 5.4.6 which implements changes required to accommodate a database schema change.

Depending on your installation type, the message may be displayed in the artifactory.log file, the $ARTIFACTORY_HOME/tomcat/logs/localhost.log file or in the command line output.

To recover from this error and, you first need to replace your current version as described below (according to your installation type).

Then you can proceed with upgrading to version 5.4.6 as required using the normal upgrade procedure, and then on to your final desired version, also, using the normal upgrade procedure.

Reinstalling Your Current Version

Reinstalling is similar to the process you went through when upgrading to your current version according to your installatian type.

For example, if you tried to upgrade from version 5.2 directly to version 5.5, you now need to reinstall version 5.2 and follow the instructions below, according to your installation type.

 Zip Installation

Follow the upgrade instructions for a Zip installation using your current version.  

Debian Installation

Follow the upgrade instructions for a Debian installation using your current version.  

If your current version is below 5.4.0, make sure to remove the $ARTIFACTORY_HOME/tomcat/webapps/access folder. This folder is a remnant of the failed attempt to upgrade to version 5.5 and is not needed in versions previous to 5.4 where the Access Service is bundled together with the Artifactory WAR. 

Docker Installation

Follow the upgrade instructions for a Docker installation using your current version.  

RPM Installation 

Follow the upgrade instructions for an RPM installation using your current version. 

If your current version is below 5.4.0, make sure to remove the $ARTIFACTORY_HOME/tomcat/webapps/access folder. This folder is a remnant of the failed attempt to upgrade to version 5.5 and is not needed in versions previous to 5.4 where the Access Service is bundled together with the Artifactory WAR.