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

Foreachsecondarynodein 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.logand 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.xmlhas 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/driver.
   5. Remove the following files and folders from your$ARTIFACTORY_HOMEfolder:
      

      • 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 theAccess 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 inthis 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 allow2 start/stop threadsas shown below (see ):

      …<引擎名称=“卡特琳娜”defaultHost =“localhost">   ...

      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,sendReasonPhrasewas added foreachTomcat connector in the server.xml file as shown in the example below:

      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

      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:

      
      

   8. If you installed Artifactory as a service, you now need to run the service

      1. For a Linux service, browse to$ARTIFACTORY_HOME/binand execute the following commandas root:$ARTIFACTORY_HOME/bin/installService.sh [USER [GROUP]]

      2. For Windows service, browse to %ARTIFACTORY_HOME%\bin. First uninstall the service by runninguninstallService.bat, then reinstall the service by runninginstallService.bat. You can now run the service through the Windows UI or as described inRunning Artifactory.

   Debian Installation

   Upgrading a Debian installation...

   1. Log in as root (or usesudo 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--6.y.z.deb

   Managing Configuration Files

   When upgrading aDebianinstallation the upgrade process overwrites the following set of configuration files:

   • system.properties
   • config.xml
   • default
   • logback.xml
   • mimetypes.xml
   • All files underopt/jfrog/artifactory/misc
   • All files underopt/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 inthis 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 allow2 start/stop threadsas shown below (see ):

   …<引擎名称=“卡特琳娜”defaultHost =“localhost">   ...

   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,sendReasonPhrasewas added foreachTomcat connector in the server.xml file as shown in the example below:

   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

   Upgrading to version 6.3 and above

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

   Upgrading to version 6.14.0 and above

   From version 6.14.0, the systemd runs successfully. Prior to upgrading to this version perform the following steps:

   1. Stop Artifactory by running the following command.

   2. Ignore any errors that may arise, and allow it to run to disable the auto start by systemd.

      systemctl stop artifactory.service

   3. Kill any running Artifactory Java process that may still be running, using the following command:

      ps -ef | grep java | grep artifactory | grep tomcat

   4. Rename the existing /etc/opt/jfrog/artifactory/default file to the new artifactory.pid file location:

      export ARTIFACTORY_PID=/var/run/artifactory.pid

   5. Run the new Debian installation

   6. Start Artifactory by running the following command:

      systemctl start artifactory.service

   
   

   Upgrading Debian OSS to Pro

   确保所有的数据仍在工件ory 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-.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 underManaging 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 inthis 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 allow2 start/stop threadsas shown below (see ):

   …<引擎名称=“卡特琳娜”defaultHost =“localhost">   ...

   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,sendReasonPhrasewas added foreachTomcat connector in the server.xml file as shown in the example below:

   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

   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:

   RPM Installation

   Upgrading an RPM installation...

   Make sure you are upgrading from v3.6 or above

   当运行RPM安装,你只能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 usingrpm --forceyou may end up deleting all of your data.

   1. Download theArtifactory Pro RPM Installer.The latest version can be downloaded from theJFrog Downloads. Previous versions can be downloaded fromLegacy Downloads.
   2. Log in as root (or usesudo 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.rpmorigor a.rpmnewextension.

   A.rpmorigextension 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.rpmnewextension means that the original file in your installation, wasnotreplaced 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 version5.4.6, you should review the instructions onUpgrading an Enterprise HA Clusterprior 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 inthis 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 allow2 start/stop threadsas shown below (see ):

   …<引擎名称=“卡特琳娜”defaultHost =“localhost">   ...

   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,sendReasonPhrasewas added foreachTomcat connector in the server.xml file as shown in the example below:

   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

   Upgrading to 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:

   Upgrading to version 6.14.0 and above

   From version 6.14.0, the systemd runs successfully. Prior to upgrading to this version perform the following steps:

   1. Stop Artifactory by running the following command.

   2. Ignore any errors that may arise, and allow it to run to disable the auto start by systemd.

      systemctl stop artifactory.service

   3. Kill any running Artifactory Java process that may still be running, using the following command:

      ps -ef | grep java | grep artifactory | grep tomcat

   4. Rename the existing /etc/opt/jfrog/artifactory/default file to the new artifactory.pid file location:

      export ARTIFACTORY_PID=/var/run/artifactory.pid

   5. Run the new RPM installation

   6. Start Artifactory by running the following command:

      systemctl start artifactory.service

   
   

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.keydirectory, to the secondary node under the$ARTIFACTORY_HOME/etc/security/master.keydirectory.
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 theAdminmodule go toAdvanced | System Logsto view the log and verify that you see an entry forHA 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 asAdmin.

5. In theAdminmodule go toConfiguration.There should be a section calledHigh Availability.When selected you should see a table with details on all the Artifactory nodes in your cluster as displayed below.

   

6. In theAdminmodule underConfiguration | General,verify that theCustom URL Basefield 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 theartifactory.logfile, the$ARTIFACTORY_HOME/tomcat/logs/localhost.logfile or in the command line output.

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

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

Reinstalling Your Current Version

重新安装类似于你去th的过程rough 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 theupgrade instructions for a Zip installationusing your current version.

Debian Installation

Follow theupgrade instructions for a Debian installationusing your current version.

If your current version is below 5.4.0, make sure to remove the$ARTIFACTORY_HOME/tomcat/webapps/accessfolder. 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 theAccess Serviceis bundled together with the Artifactory WAR.

Docker Installation

Follow theupgrade instructions for a Docker installationusing your current version.

RPM Installation

Follow theupgrade instructions for an RPM installationusing your current version.

If your current version is below 5.4.0, make sure to remove the$ARTIFACTORY_HOME/tomcat/webapps/accessfolder. 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 theAccess Serviceis bundled together with the Artifactory WAR.