Purpose

In some cases, it is necessary to perform an offline upgrade of Hipchat Server due factors such as:

• Outbound proxy or network issues that prevent contact with our upgrade servers
  
• Organizational requirements prevent Hipchat Server from directly downloading upgrades from the Internet

This article describes how to perform an offline upgrade to work around these scenarios.

Requirements

• A separate workstation with access to the internet to download Hipchat upgrade packages which can then be transferred over to the server.
• Access to the Hipchat Server within the organization's internal network for the purpose of logging in remotely (via SSH) as well as transferring files. 
  

Solution

Phase 1: Download the Required Files

For workstations capable of running bash scripts, please see the instructions below:

1. Download the pre-offline-upgrade-downloader script to a separate workstation/machine using wget or an equivalent utility. For example:

   wget https://s3.amazonaws.com/hipchat-server-stable/utils/_pre-offline-upgrade-downloader.sh

2. Open the script in a text editor.

3. To download the latest production release of Hipchat Server for ugprade, please change the "HCCHANNEL" value on line 3 of the script from "beta" to "production", otherwise, do not change the value if an upgrade to the Beta release is desired:

   HCCHANNEL="production"

4. Next, modify the "TARGET" variable in the script on line 6 to point to a local directory on the workstation. In the example below, the target is set to the '/Users/jsmith/Downloads/upgrade' directory:

   TARGET="/Users/jsmith/Downloads/upgrade/"

   Any files in the "TARGET" directory will be deleted before the script begins the download.

   
   
   

5. Make the script executable using the following command:

   chmod +x _pre-offline-upgrade-downloader.sh

6. Execute the script on the workstation. 

   ./_pre-offline-upgrade-downloader.sh

   The script will download a large tar file containing packages for the upgrade and some additional supporting files needed to complete the upgrade. An example file listing for Hipchat Server 2.0.4 will look similar to the following:

   ls -l /Users/jsmith/Downloads/upgrade
   -rw-r--r--  1 jsmith  staff  1539913700 16 Aug 17:26 hcs-2.0.4-2016.08.15.220817.tar.gz
   -rw-r--r--  1 jsmith  staff        3105 16 Aug 17:26 hipchat.server.manifest
   -rw-r--r--  1 jsmith  staff          18 16 Aug 17:26 hipchat.server.release
   -rw-r--r--  1 jsmith  staff           6 16 Aug 17:26 hipchat.server.version
   -rw-r--r--  1 jsmith  staff          94 16 Aug 17:26 latest
   -rw-r--r--  1 jsmith  staff          69 16 Aug 17:26 md5sum
   -rw-r--r--  1 jsmith  staff         165 16 Aug 17:26 sha512sum
   -rw-r--r--  1 jsmith  staff         417 16 Aug 17:26 sources.list

   If the server to be upgraded is at version 1.3.9 or below, an additional script file must be downloaded to the workstation using 'wget' or equivalent utility:

   wget https://s3.amazonaws.com/hipchat-server-stable/utils/_partial_upgrade_pre_kernel_continuance.sh

   Also, download hipchat-server-key.pub

For workstations running Windows with no access to a bash shell, please see the instructions below:

1. Download the pre_offline_upgrade_downloader powershell script from this URL:

   https://s3.amazonaws.com/hipchat-server-stable/utils/pre_offline_upgrade_downloader.ps1

2. Open the file in a text editor and change the target to a desired directory to download the files to, for example:

   $TARGET="C:\Users\joeu\hipchat"

3. Save and close the file.  
4. Execute the powershell script. The script will download a large tar file containing packages for the upgrade and some additional supporting files needed to complete the upgrade.

5. The resulting file list should be the same as what is described in Step 6 above for Unix / Linux workstations.  

   If the server to be upgraded is at version 1.3.9 or below, please also download the offline upgrade script directly from the URL below:

   https://s3.amazonaws.com/hipchat-server-stable/utils/_partial_upgrade_pre_kernel_continuance.sh

   Also, download hipchat-server-key.pub

Phase 2: Transfer files to the Hipchat Server from the workstation

1. Log in to the Hipchat Server's command line and run this command:

   mkdir /home/admin/hipchat/

2. Gain root access:

   sudo dont-blame-hipchat

3. Create the following directory:

   mkdir /file_store/temporary

4. Transfer all the files gathered from the pre-offline-upgrade-downloader script in Phase 1 from the workstation to /home/admin/hipchat on the Hipchat Server using "scp" (for Unix-based workstations), WinSCP (for Windows workstations), or any preferred file transfer tool.  Once the files are copied to /home/admin/hipchat, please run the following commands on the server to copy the files to /file_store/temporary:

   
   

   sudo dont-blame-hipchat
    
   cp /home/admin/hipchat/* /file_store/temporary/

   
   
   

   If _partial_upgrade_pre_kernel_continuance.sh script and hipchat-server-key.pub were also downloaded for upgrading an older release of Hipchat Server v1.3.9 and below, then make sure to transfer the script from the workstation to the /home/admin directory on Hipchat Server. There is no need to copy this script or the key file to /file_store/temporary. The key and the script will be used in the steps below, where applicable.

   
   

   
   

Phase 3: Upgrade the Server

If the Hipchat Server is at version 1.3.9 or lower, run the following steps: 

1. Log in to the Hipchat Server's command line and execute the following commands to initiate the upgrade:

   cd /home/admin
   sudo dont-blame-hipchat
   apt-key add /home/admin/hipchat-server-key.pub
   chmod +x ./_partial_upgrade_pre_kernel_continuance.sh
   ./_partial_upgrade_pre_kernel_continuance.sh

2. The upgrade can take several minutes to complete. Please do not stop the upgrade script pre-maturely (by pressing Ctrl+C for example) or reboot the server during the upgrade.

3. When the upgrade completes, the script will display the following message on the console:

   "WARNING: A reboot of your HipChat Server is required" 

4. Reboot the server when prompted. After the server reboot, your OS should be good to start the actual Hipchat Server upgrade. 

If the Hipchat Server is at version 1.4.0 or higher, run the following step: 

• Log in to the Hipchat Server's command line and execute the following to initiate the upgrade:

  hipchat upgrade --offline

  The command will notify the user that the upgrade completed completed successfully.

Phase 4: Verification

1. Once the upgrade completes and any required reboots are performed, verify that users can log in successfully to the Hipchat Server and that chats and any integrations are functioning normally.

2. Upgrades from 1.3.x or older also include a full Operating System upgrade to Ubuntu 14.04, which includes a new kernel.  After the reboot, verify that the server is running the new, 3.13 kernel by running the uname -a command from the Hipchat Server command line.  The results should look similar to the following:

   uname -a
   Linux myhipchat.example.com 3.13.0-77-generic #121-Ubuntu SMP Wed Jan 20 10:50:42 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux

3. From the Hipchat Server command line, the following command can verify that the server is on the new release.  In the example below, the Hipchat Server was upgraded to version 2.0.4:

   $ cat /etc/hipchat-release
   Atlassian HipChat 2.0.4 (2016.08.15.220817)

Getting Help:

• If problems are encountered either during or after the upgrade, please contact Atlassian Support and include supporting logs as outlined in our Contacting Hipchat Server Support documentation.