Skip to main content

Upgrade a base deployment with ArcGIS Enterprise Builder

ArcGIS Enterprise Builder can upgrade a base deployment previously installed by the builder. Deployments set up using another method cannot be upgraded using the builder. The same limitations apply as with installation.

Summary of upgrade

The following is a summary of the steps you must take to upgrade a base deployment using ArcGIS Enterprise Builder:

  1. Review and complete prerequisite steps.

  2. Upgrade ArcGIS Web Adaptor instances.

  3. Run the ArcGIS Enterprise Builder setup program to install the ArcGIS Enterprise components.

  4. Use the configuration wizard or upgradebasedeployment command line utility to perform the upgrade.

  5. Complete postupgrade steps.

Prerequisites

Carefully review the following information and complete any required actions before you upgrade using ArcGIS Enterprise Builder:

  • Read the system requirements for ArcGIS Enterprise Builder to ensure your hardware meets current requirements.

  • Confirm that your existing version of ArcGIS Enterprise is supported for direct upgrade to this version.

    Note:

    Versions 10.7.1 and earlier are retired. Upgrading from these versions requires two interim upgrades. Read the 11.5 upgrade documentation for information.

  • You must reauthorize your software for 12.1. You can access new authorization files in My Esri, along with the ArcGIS Enterprise Builder file.

  • The Run As accounts for all ArcGIS Enterprise software components must be identical.

Upgrade your ArcGIS Web Adaptor instances

The ArcGIS Enterprise Builder cannot upgrade ArcGIS Web Adaptor (Java Platform), as an additional step is needed to undeploy the web adaptor from the Java web server. Perform these steps prior to running ArcGIS Enterprise Builder.

  1. Change directories to the ArcGIS Web Adaptor installation folder as an administrator.

  2. Uninstall the instance of ArcGIS Web Adaptor file from the machine.

    This removes the ArcGIS Web Adaptor instances from the Java web server.

  3. Undeploy both instances of ArcGIS Web Adaptor from the application server.

  4. Install ArcGIS Web Adaptor 12.1.

  5. Deploy two instances of ArcGIS Web Adaptor to your application server using the arcgis.war file: one for ArcGIS Server and one for Portal for ArcGIS.

You can now continue the ArcGIS Enterprise Builder upgrade process.

Run the ArcGIS Enterprise Builder setup program

ArcGIS Enterprise Builder is designed to detect and upgrade an existing installation of ArcGIS Enterprise Builder components. To start the upgrade, run ./Setup from the location where ArcGIS Enterprise Builder was extracted, and follow the prompts to complete the upgrade of the ArcGIS Enterprise Builder components. The setup must be run as the user account that installed the existing ArcGIS Enterprise Builder components.

When running the setup, the ArcGIS Server authorization files can be passed using the same method documented in Installing ArcGIS Enterprise Builder silently, or after the setup has completed using the software authorization tools found in the ArcGIS Server tools folder. This is installed to <EnterpriseBuilderInstallPath>/arcgis/server/tools/authorizeSoftware.

Note:

The installation path cannot be changed during the upgrade process.

Follow the steps below to install updated base ArcGIS Enterprise components using ArcGIS Enterprise Builder.

  1. Launch the setup program using the Builder.exe file.

  2. Read the master agreement and accept it, or exit if you do not agree with the terms.

    The destination folder of your previously installed ArcGIS Enterprise Builder components will be already provided. You cannot change this destination folder during an upgrade.

  3. Click Next to continue the setup program.

  4. Provide the password for the account specified.

    This is the account all ArcGIS Enterprise components were run as. You must use the correct password for this user or the setup program will return an error message. Contact your system administrator if you do not know the password for the specified user account.

    When upgrading an existing deployment, you will not be able to change the ArcGIS Web Adaptor (IIS) names for your hosting server or portal. The setup program will configure ArcGIS Web Adaptor (IIS) names based on your previous configuration.

  5. At the software authorization dialog box, provide the location of the authorization files for Portal for ArcGIS and ArcGIS Server.

    These authorization files must be for the version you are installing.

Once the installation is updated, the configuration wizard automatically launches in your default web browser.

Upgrade the ArcGIS Enterprise deployment

After the installation is complete, you can use the configuration wizard to upgrade ArcGIS Enterprise, or close the browser and use the upgradebasedeployment command line utility to upgrade the base deployment.

Upgrade using the configuration wizard

To upgrade using the configuration wizard, complete the following steps:

  1. If it's not already open, browse to the configuration wizard's URL, which is in the format http://mymachine.myexample.com:6080/arcgis/enterprise.

    Alternatively, you can search your machine for the ArcGIS Enterprise Configuration Wizard and launch it using the shortcut.

    Caution:

    Do not close or refresh the browser when the upgrade is in progress.

  2. Read the information on the initial landing page, which explains that the wizard needs to use a secure connection, and click Next.

    The wizard redirects to secure port 6443. The browser will return a security warning; this is expected the first time you access the secure wizard. Continue past the warning. How you continue varies by web browser.

  3. On the License and Upgrade ArcGIS Enterprise page of the wizard, browse to your portal .json file that contains authorized user types and apps.

    This file is obtained from My Esri.

  4. Click Upgrade.

    This triggers the upgrade process and opens a progress page (Configuring a Deployment). The upgrade process will take a few minutes to complete.

When the upgrade wizard is complete, a final page will confirm this. Close this page to follow the postupgrade steps.

Upgrade using the command line utility

After you install the software with ArcGIS Enterprise Builder, you can upgrade the base deployment using the upgradebasedeployment command line utility.

Run the command line utility using the account that installed the software.

The upgradebasedeployment command line utility is located in <ArcGIS Server installation directory>/tools/upgradebasedeployment.

You must run the command line utility as a Windows administrator.

The upgradebasedeployment command line utility is located in <ArcGIS Server installation directory>\tools\upgradebasedeployment.

By default, that location is C:\Program Files\ArcGIS\Server\tools\upgradebasedeployment .

The following describes the parameters used in the command line utility:

  • -lf—Specifies the path to the portal .json license file. If you are upgrading to a version within the same release series, this property is ignored and you can import a new license file after upgrading if needed. The portal .json license file is obtained from My Esri.

  • -s—Upgrades the base ArcGIS Enterprise deployment silently; you will not be prompted to proceed.

  • -h—Displays help and exits the program.

Follow these steps to upgrade ArcGIS Enterprise using the upgradebasedeployment utility:

  1. Open a command prompt.

  2. In the command prompt, change the working directory to the location of the upgradebasedeployment utility, for example, <ArcGIS Server installation directory>/tools/upgradebasedeployment.

  3. In the command prompt, change the working directory to the location of the upgradebasedeployment utility, for example, <ArcGIS Server installation directory>\tools\upgradebasedeployment.

  4. Type the upgradebasedeployment command and parameter directly in the command prompt.

    ./upgradebasedeployment.sh -lf <path to portal json file> -s

    upgradebasedeployment.bat -lf <path to portal json file> -s

Once the upgrade completes, you are provided with links to the portal and hosting server site.

Proceed with the postupgrade steps.

Postupgrade steps

After you upgrade the ArcGIS Enterprise deployment using ArcGIS Enterprise Builder, confirm the deployment is functional. There are additional optional steps you may need to complete as well.

  1. Verify that you can sign in to the organization through the ArcGIS Web Adaptor URL as an administrator. The URL is formatted https://webadaptorhost.example.com/webadaptorname/home.

    Note:

    Check the index using the ArcGIS Portal Administrator Directory. If it's out of sync, reindex Portal for ArcGIS.

  2. Optionally, use the serverScan.py and portalScan.py scripts to check for security best practices with your upgraded ArcGIS Server and ArcGIS Enterprise portal.