Multiple instances of Iguana using a single install folder

Introduction

Doing a manual installation can make upgrades much easier and gives you much more control over your servers running Iguana.

The key idea is that the following categories of files should be cleanly separated:

      • Configuration files:
        • IguanaConfiguration.xml
        • Iguana uses two GIT Repositories
        • IguanaLicense file
        • VMD files if you are using classical Iguana channels
      • Log files: best stored on a separate high speed partition with a large capacity
      • Application files: We can use a single install directory for multiple Iguana instancesƒ

Taking the time to lay things out in this manner will make upgrades a lot easier. We’ve put the right options in place to make this kind of deployment possible since we make extensive use of this functionality internally. We maintain a large farm of Iguana servers for testing, and for our own integration infrastructure.

If you have any questions please contact us at support@interfaceware.com.

Note: We use mostly Windows examples – but the same principles apply on Linux systems.

Install Instructions [top]

Windows install instructions:

  1. Download the latest Iguana manual installer file:
  2. Install Iguana:
    • Create the Iguana install directory: You can install in any directory you choose.

      We intentionally did not install in the installer default directory C:\Program Files\iNTERFACEWARE\Iguana\ as access is restricted by Windows UAC, and you would need to disable and re-enable UAC for the install process and for any later upgrades.

      • For Windows we used: “C:\iNTERFACEWARE”
    • Unpack the manual installer file into the C:\iNTERFACEWARE  directory
    • This will usually create an install directory named C:\iNTERFACEWARE\iNTERFACEWARE-Iguana
    • Rename the install directory to C:\iNTERFACEWARE\IguanaApp
  3. Create the three Iguana working directories: <install path>\Iguana[X], we used:
  4. Copy the Iguana service files into the working directories:
    • Copy the iguana_service.exe and iguana_service.hdf files
  5. Rename the Iguana service files to match the working directories:

    The names for the .exe and the .hdf file must match exactly. Later when you run iguana_serviceA.exe to install the corresponding iguana service it expects to find a matching iguana_serviceA.hdf file in the same directory.

    • iguana_serviceA.exe and iguana_serviceA.hdf
    • iguana_serviceB.exe and iguana_serviceB.hdf
    • iguana_serviceC.exe and iguana_serviceC.hdf
  6. Change the following four settings in iguana_service hdf files:
      1. Set service_display_name to a unique name
        • For example in iguana_serviceA.hdf we used “iNTERFACEWARE Iguana Instance A”
      2. Set service_name to a unique name
        • For example in iguana_serviceA.hdf we used “IguanaA”
      3. Update command_line to set the iguana.exe and the working directory for Windows systems:
        • For example in iguana_serviceA.hdf this is the path for the iguana.exe 
          command_line=C:\iNTERFACEWARE\IguanaApp\iguana.exe --working_dir C:\iNTERFACEWARE\IguanaA\
        • And we added the --working_dir parameter to set the working directory 
          command_line=C:\iNTERFACEWARE\IguanaApp\iguana.exe --working_dir C:\iNTERFACEWARE\IguanaA\

          Tip: Always put quotes around paths that have spaces in them, for example:

          command_line=C:\IguanaApp\iguana.exe --working_dir "C:\Program Files\iNTERFACEWARE\Iguana\IguanaDev"

         

      4. Alternatively update command_line_unix to set the iguana.exe and the working directory for Linux systems:
        • For example in iguana_serviceA.hdf: 
          command_line_unix=/home/iguana/iguana_app/iguana --working_dir /home/iguana/A/

    Tip: You can use the example iguana_service hdf files below to follow our structure – or you can change the settings as indicated above.

  7. Install the three Iguana services manually:

    More info: Windows: How to Install/Uninstall the Iguana Service From a Command Prompt.

  8. Run each of Iguana services to initialize the working directory:

    Initially all three Iguana instances will be setup to use the default port 6543 (URL: localhost:6543). This means you can only start one service at a time as there will be a port conflict. Therefore you need to stop each service before running the next one. We will change the ports in the next step to resolve this conflict.

  9. Change config settings:

    The examples shown below are for the Iguana A instance, you need to change names and increment port numbers for the other instances. See the example IguanaConfiguration.xml files below where the required changes are highlighted in yellow.

    • Change the setting in the configuration file: <working dir>\IguanaConfigurationRepo\IguanaConfiguration.xml
      • For the IguanaA example: C:\iNTERFACEWARE\IguanaA\IguanaConfigurationRepo\IguanaConfiguration.xml
    • Set web port: web_config>port: 
      <web_config
   port="8000"
    • Add the server name entry: server_label: 
      <web_config
   server_label="Iguana A Instance"
    • Set log file directory: log_directory:

      You can setup the log files anywhere – for the best performance use the fastest possible disk device. See Log Configuration and Performance for more information. As our test machine does not have a D drive we had to use C drive – this in not good practice in fact it is probably the worst place to put the logs (as they will be competing with the operating system and other programs for disk access)

      • Our example configuration uses D drive which would be a fast disk device dedicated to the logs: 
        <log_config
   log_directory="D:/iNTERFACEWARE/iguanaA/logs/"
      • We had to use C drive on our test machine – please do not put your logs on C drive: 
        <log_config
   log_directory="C:/iNTERFACEWARE/iguanaA/logs/"
    • Set plugin port: rpc_config>port:
      NOTE: It’s not essential to change this but if you don’t you will get a (harmless) error when Iguana starts up

      <rpc_config
   port="7000"/>
  10. Set HTTP(S) channels port in the Iguana Settings:

    A new https_channel_server element for this setting will be added to your settings in IguanaConfiguration.xml. But as the entry is not included in the default configuration file it is easier to use Settings to add the the entry than to edit IguanaConfiguration.xml.

Upgrade Instructions [top]

These instructions are intended for upgrading Iguana from V6 → V6 (or V5 → V5). If you are upgrading from V5 → V6 please read Upgrade to Iguana 6.

  1. Stop all the Iguana services that use the shared install files:
  2. CRITICAL STEP: Backup or copy all the Iguana instances and the Iguana install directory:
  3. Setup some test channels:

    You should not run live channels during testing as you could potentially damage live data. The safest way to test upgrades is to use a test server that is a copy of the live server.

    Note: We are intentionally setting up test channels before we upgrade the Iguana server. This is much safer because if you (unintentionally) start any production channels they will safely process data using your current installation.

  4. Download the latest Iguana manual installer file:
  5. Rename the previous install directory:
  6. Extract the iguana_noinstaller zip file
  7. Use one Iguana instance to test that everything is working correctly:

    You should not run live channels during testing as you could potentially damage live data. The safest way to test upgrades is to use a test server that is a copy of the live server.

    • The safest way to test the upgrade is using a test server – see step three:
    • For testing on a production server:
      • Make a copy of the working directory instance that you will use to test
        • For example if we used Iguana Instance A for testing then we would copy C:\iNTERFACEWARE\IguanaA\
    • Start your chosen Iguana service in safe mode:
        • You need to run Iguana in safe mode to prevent any channels from starting automatically
        • Open a command prompt and run these commands 
          cd <iguana install directory> 
iguana --run --safe_mode --working_dir <Iguana working directory> 

For example: 
cd C:\iNTERFACEWARE\IguanaApp 
iguana --run --safe_mode --working_dir C:\iNTERFACEWARE\IguanaA
  8. Confirm that everything is running as expected
  9. If there are problems rollback to the previous version:
    • Stop all Iguana instances that are using the shared install – there should only be the one that you are using for testing
    • Rename the new install directory
      • Keeping it for further investigation later is better than just deleting it
    • Reinstate the “old” install directory by renaming it to its original <install dir> name
    • For example we would rename C:\iNTERFACEWARE\IguanaApp_old_601 back to C:\iNTERFACEWARE\IguanaApp
    • At this point the system should work exactly as it did before you upgraded
    • Alternatively you can restore from the backup from step 2
  10. If there are no problems you can now restart all your Iguana instances and their channels

How it Works [top]

We use a single Iguana install for three (or more) Iguana instances, each with their own separate service and working directory.

  • We use one common Iguana install directory
  • We use one working directory for each Iguana instance
    • The working directory contains files specific to that instance, including:
      • The Iguana service setup file, for example: iguana_serviceA.exe
      • Iguana git repositories
      • The Iguana configuration file <working dir>\IguanaConfigurationRepo\IguanaConfiguration.xml
      • etc.
    • NOTE:  All relative VMD file paths are based on the working directory
  • We customize the service install settings files (like: iguana_serviceA.hdf) in each working directory, so that:
    • They all use the iguana executable in the common install directory
    • Each instance has its own unique service settings
    • Each instance points to its own working directory
  • We customize the Iguana configuration files (IguanaConfiguration.xml) in each working directory, so that:
    • Each instance gets its own unique server name
    • Each instance has its own separate log file directory
    • Each instance listens on its own unique web port
    • Each instance has its own unique plugin port
      NOTE: It’s not essential to change this but if you don’t you will get a (harmless) error when Iguana starts up
    • Each instance gets its own unique HTTP(S) channels port

Example iguana_service.hdf files [top]

This file is located in the Iguana working directory.

The service install settings file for each instance of Iguana show the three required changes in yellow:

  • The service name: service_name
  • The service display name: service_display_name
  • The iguana executable path in: command_line or command_line_unix
  • The working directory as –working_dir in: command_line or command_line_unix

iguanaA.hdf

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

iguanaB.hdf

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

iguanaC.hdf

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

Example IguanaConfiguration.xml files [top]

This file is located at <working directory>\IguanaConfigurationRepo\IguanaConfiguration.xml.

The configuration file for each instance of Iguana show the five required changes in yellow:

  • The web port that the Iguana server listens on and uses in the its URL (localhost:<port>): web_config>port
  • The server name: web_config>server_label
  • The log directory used to store the log files: log_config>log_directory
  • The plugin port: rpc_config>port
    NOTE    : It’s not essential to change this but if you don’t you will get a (harmless) error when Iguana starts up
  • The HTTP(S) channels port: https_channel_server>port

Tip: The plugin port is used by Iguana’s legacy plugin feature. Our recommended best practice is to use web services instead as they are superior and easier to implement.

Note: The Location of the configuration file IguanaConfiguration.xml in Iguana 6 is different from Iguana 5, it has been moved into the IguanaConfigurationRepo subdirectory of the working directory.

IguanaConfiguration.xml A

This file is located at C:\iNTERFACEWARE\IguanaA\IguanaConfigurationRepo\IguanaConfiguration.xml which is the defined working directory for the Iguana A instance.

<iguana_config
   encryption_key="Xb9+OWCgTi3NSSUY2UTGJg=="
   major_version="6"
   minor_version="0"
   build_number="1"
   service_log_guid="9B8CD31EE07B29FAE3CCCE25B9503C63"
   startup_clean="true">
<web_config
   port="8000"
   session_timeout="1200"
   use_https="false"
   server_label="Iguana A Instance"/>
<email_config
   ...
</email_config>
<channel_groupings>
   ...
</channel_groupings>
<log_config
   log_purge_time_hour="0"
   log_purge_time_minute="0"
   log_directory="D:/iNTERFACEWARE/iguanaA/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7000"/>

IguanaConfiguration.xml B

This file is located at C:\iNTERFACEWARE\IguanaB\IguanaConfigurationRepo\IguanaConfiguration.xml which is the defined working directory for the Iguana B instance.

<iguana_config
   encryption_key="Xb9+OWCgTi3NSSUY2UTGJg=="
   major_version="6"
   minor_version="0"
   build_number="1"
   service_log_guid="9B8CD31EE07B29FAE3CCCE25B9503C63"
   startup_clean="true">
<web_config
   port="8001"
   session_timeout="1200"
   use_https="false"
   server_label="Iguana B Instance"/>
<email_config
   ...
</email_config>
<channel_groupings>
   ...
</channel_groupings>
<log_config
   log_purge_time_hour="0"
   log_purge_time_minute="0"
   log_directory="D:/iNTERFACEWARE/iguanaB/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7001"/>

IguanaConfiguration.xml C

This file is located at C:\iNTERFACEWARE\IguanaC\IguanaConfigurationRepo\IguanaConfiguration.xml which is the defined working directory for the Iguana C instance.

<iguana_config
   encryption_key="Xb9+OWCgTi3NSSUY2UTGJg=="
   major_version="6"
   minor_version="0"
   build_number="1"
   service_log_guid="9B8CD31EE07B29FAE3CCCE25B9503C63"
   startup_clean="true">
<web_config
   port="8002"
   session_timeout="1200"
   use_https="false"
   server_label="Iguana C Instance"/>
<email_config
   ...
</email_config>
<channel_groupings>
   ...
</channel_groupings>
<log_config
   log_purge_time_hour="0"
   log_purge_time_minute="0"
   log_directory="D:/iNTERFACEWARE/IguanaC/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7002"/>

 

Tagged: