Iguana production server upgrade

In this tutorial you will learn how to upgrade a basic Iguana Production Server, following our recommended Best Practice Production Deployment for Iguana.

This tutorial makes these assumptions:

  1. That you are using Windows.
  2. You wish to upgrade to the current release of Iguana.
  3. There is only one instance of Iguana installed on the server.

This process can easily be adapted for other operating systems, and multiple instances (see notes and tips in the instructions).

Obviously there is no single solution for all scenarios, so please contact support at support@interfaceware.com if you need help adapting this procedure for your installation.

Tutorial Instructions [top]

  1. For this tutorial we assume that Iguana 5.6.20 is the current release of Iguana, and that we are upgrading from an earlier version like 5.6.19.
  2. Make sure you use an account with Administrator privileges.
  3. Check the “maintenance expiry” date on your instance of Iguana:
    1. Go to Settings > License Entitlement and check the Maintenance Expiry Date:
    2. If this date is earlier than the release date of the version you are upgrading to, then you will need to get a new license to run this version:
      1. You can contact support at support@interfaceware.com with your Iguana ID and request an updated license code with a more recent date.
      2. You can also log into your user account and activate a temporary license to get running immediately, and then email us later for a permanent license code.
      3. Also if you upgrade without checking and the server won’t start don’t panic, just log into your user account and activate a temporary license to get up and running , and then email us for a permanent code.
      4. See our Installation FAQS for more information on these issues.
  4. Create a versioned (empty) install directory C:\Iguana-5-6-20\
    Note: The directory name is in the format C:\Iguana-<version number>\, i.e., for 6.2.10 use C:\Iguana-6-2-10

    Tip: Iguana can run from any location (with write permission), so if your install directory is different. Simply create a new versioned directory to match your chosen structure.

  5. Your current and historical install directories will look something like this:
  6. Download the latest zip file manual installer version of Iguana:
    1. Click the Other downloads are available below link on our iNTERFACEWARE Downloads page.
    2. From Upgrading Iguana? choose either the 32 or 64 bit manual installer to match your operating system:

      Tip: Downloads for other operating systems are available from the iguana directory on our download site: http://dl.interfaceware.com/iguana/, for more information see this page: Download other install files.

  7. Extract the files into the new created install directory:
    1. Open the install zip (double click on it), and then select all the files (Ctrl+A) and drag them into the install directory C:\Iguana-5-6-20\
  8. Update the Iguana Service configuration details in the C:\Iguana-5-6-20\iguana_service.hdf file:
    1. Append --working_dir C:\IguanaConfig\ argument to the command_line=iguana.exe entry.
      The result should look like this:

      application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana
   service_name=Iguana
   service_description=HL7 Integration Engine
   command_line=iguana.exe --working_dir C:\IguanaConfig\
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}

      If your working directory path contains spaces (like C:\Program Files\iNTERFACEWARE\Config\) you will need to enclose it in quotes, like this:

      application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana
   service_name=Iguana
   service_description=HL7 Integration Engine
   command_line=iguana.exe --working_dir "C:\Program Files\iNTERFACEWARE\Config\"
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}

      Note: For Linux, Unix and Mac you need to append --working_dir C:\IguanaConfig\ argument to the command_line_unix=iguana.exe entry instead.

      Tip: You may want also to change the display_name and/or the service_name to match the version number of Iguana, to make it more obvious which version the service is running.

      The result would look like something this:

      application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana 5.6.20
   service_name=Iguana_5_6_20
   service_description=HL7 Integration Engine
   command_line=iguana.exe --working_dir C:\IguanaConfig\
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
  9. Uninstall the old Iguana Service:
    1. Run the command line console (cmd) as Administrator.
    2. Change to old install directory, run the command: cd C:\Iguana-5-6-19\
    3. Install the service, run the command: iguana_service --uninstall

      Note: If you are using the same service_name as previously then uninstalling the old service is not strictly necessary, as the install command (iguana –install) will stop the existing service and replace it with the new service (with the same service name).

      However we recommend that you perform the uninstall to “prove” that old service is removed (rather than trusting the install command to do a “silent” uninstall).

  10. Install the new Iguana Service:
    1. Run the command line console (cmd) as Administrator.
    2. Change to new install directory, run the command: cd C:\Iguana-5-6-20\
    3. Install the service, run the command: iguana_service --install
  11. Start the Iguana service.
  12. Open the Iguana Dashboard and check that you are upgraded to the latest version:
  13. If the wrong (old) version is running, you just need to repeat the uninstall (step 9) and the install (step 10).
    Note: If you (intentionally) have multiple installs on the machine you may just have started the wrong service.
  14. Perform any tests that you deem necessary to confirm that your channels are working correctly.
    Note: We assume that you have previously tested the upgrade in a non-production environment.
  15. Do not remove the old install directory:
    1. We strongly recommend keeping the previous install directory so it is possible to rollback .
      Note: It is not large, roughly 70 MB
    2. You can keep several versions, or even the complete upgrade history, if you wish.
      Note: It is very unlikely that would you need to rollback to older versions.
    3. You may want to archive (move) the old install directories.

      Note: Rolling back to an older version of Iguana is a very simple:

      1. Use the command line to change into the application directory of the current Iguana version.
      2. Run the command: iguana_service –uninstall
      3. Confirm that the service is uninstalled.
      4. Use the command line to change into the application directory of the older Iguana version to rollback to.
      5. Run the command: iguana_service –install
      6. Restart the Iguana service.
      7. Login into the Iguana dashboard and verify that the channels are running correctly.

      Warning: If you are using any new features in the current install you will need to disable them before rolling back, you can do this by setting the scripts in the affected channels to run earlier milestones (or by modifying the scripts).

  16. And that’s all there is to it, you’re done!

Multiple Server Instances [top]

Upgrading multiple Iguana Server instances on the same machine is simple, there are couple of extra steps.

  1. Create separate new (empty) install directories for each instance:
    1. We assume our instances are called Iguana_prod1 and Iguana_prod2.
    2. Create two install directories: C:\Iguana_prod1-5-6-20\ and C:\Iguana_prod2-5-6-20

      Tip: It is possible for multiple instances to share the same application files. This approach can be useful if you wish ensure that all instances will be using the same version of Iguana.It also simplifies the upgrade process as you only need to upgrade a single shared installation directory.

      If you are using this structure you only need to create one new (empty) install directory, and upgrade only that single directory.

      See this page for more information: Manual installation Best Practices.

  2. Repeat the Tutorial Instructions in the previous section for each instance that you are upgrading, using the new directories for each instance.
  3. When you update the service details (step 8) you also need to use a different Working Directory, Service name and Display name for each instance:
    1. Update the command_line, service_name and the service_display_name in the iguana_service.hdf file:
      The results should look something like this:

      application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana_prod1
   service_name=Iguana_prod1
   service_description=HL7 Integration Engine
   command_line=iguana.exe --working_dir C:\Iguana_prod1-Config\
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
      application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana_prod2
   service_name=Iguana_prod2
   service_description=HL7 Integration Engine
   command_line=iguana.exe --working_dir C:\Iguana_prod2-Config\
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}

      Tip: The Multiple Server Instances section in the Iguana production server install tutorial has more information on setting up multiple instances.

More Information [top]