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
    • vcs_repo.sqlite
    • IguanaLicense file
    • vmd files if you are using classical Iguana channels
  • Log files: best stored on a separate partition with a large capacity
  • Application files

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.

This document applies to both Windows and non-Windows operating systems. Small differences exist which are indicated where needed.

So let’s say you were on Windows and you wanted to have 3 Iguana instances like this:

# iguana_service.exe HDF File Working Directory
A C:\App\iguanaA.exe C:\App\iguanaA.hdf C:\IguanaA\
B C:\App\iguanaB.exe C:\App\iguanaB.hdf C:\IguanaB\
C C:\App\iguanaC.exe C:\App\iguanaC.hdf C:\IguanaC\
# IguanaConfiguration.xml Log Dir Web Port Plugin Port
A IguanaConfigurationRepo\IguanaConfiguration.xml D:\iguanaA\logs\ 8000 7000
B IguanaConfigurationRepo\IguanaConfiguration.xml D:\iguanaB\logs\ 8001 7001
C IguanaConfigurationRepo\IguanaConfiguration.xml D:\iguanaC\logs\ 8002 7002

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.

We would unpack the application files from the zip file (tarball for non-Windows systems) for the manual install into C:\App\. This allows all three instances to share the same application files.

Then for each instance we would:

  1. Copy the iguana_service.exe from the application distribution into the C:\App directory and rename it to iguanaA.exe, etc. (POSIX operating systems do not have .exe extensions).
  2. Copy and edit an associated hdf file which must have the same name as the executable from step 1. Also, always put quotes around paths that have spaces in them.
  3. Edit this file so that:
    • The name and the description of the service is set correctly (only matters on Windows)
    • The complete path of the Iguana executable, this determines what version of Iguana will be run.
    • Set the –working_dir parameter to the specific working directory of the Iguana instance. This is where:
      • The IguanaConfiguration.xml file is located
      • The vcs_repo.sqlite fossil repository is located
      • VMDs with relative paths are loaded from
  4. The IguanaConfiguration.xml file for each instance needs to have a different:
    • Log directory
    • Web port
    • Plugin port
  5. Each Iguana instance will require it’s own IguanaLicense file which you can set through the GUI.
  6. For Windows we would invoke iguana[#].exe –install to register the service (see Manual Install).

This is what we do internally. We make a lot of use of the Global Dashboard to make monitoring all these Iguana instances easy and it enables us to do things like upgrade separate instances at different times rather than having to upgrade all of them at once and so on.

It is possible to run different versions of Iguana simultaneously using this type of configuration.

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

iguanaA.hdf [top]

This configuration file for the A instance of Iguana supplies the working directory where the IguanaConfiguration.xml and vcs_repo.sqlite files are stored. All relative VMD file paths are based on this directory.

Notice how the explicit path to the Iguana executable is given as C:\IguanaApp\iguana.exe (for non-Windows operating systems /home/iguana/iguana_app/). This is the location of the unzipped application files.

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

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"

IguanaConfiguration.xml A [top]

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

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.

There are three key settings which need to be different from the other 2 Iguana instances:

  1. The web port that the user interface of the Iguana server uses: 8000
  2. The log directory used to store the log files: D:\iguanaA\logs\
  3. The plugin port (it’s not essential to change this but if you don’t you will get a error when Iguana starts up): 7000

The plugin port is used for plugins with Iguana. In general we encourage you to use web services with the Translator instead of plugins with Iguana 5.0.

Here’s some of the content of an IguanaConfiguration.xml file with highlights over the parts of the file you would need to edit:

<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:/iguanaA/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7000"/>

iguanaB.hdf [top]

This configuration file for the B instance of Iguana supplies the working directory where the IguanaConfiguration.xml and vcs_repo.sqlite files are stored. All relative VMD file paths are based on this directory.

Notice how the explicit path to the Iguana executable is given as C:\IguanaApp\iguana.exe (for non-Windows operating systems /home/iguana/iguana_app/). This is the location of the unzipped application files.

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

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"

IguanaConfiguration.xml B [top]

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

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.

There are three key settings which need to be different from the other 2 Iguana instances:

  1. The web port that the user interface of the Iguana server uses: 8001
  2. The log directory used to store the log files: D:\iguanaB\logs
  3. The plugin port (it’s not essential to change this but if you don’t you will get a error when Iguana starts up): 7001

The plugin port is used for plugins with Iguana. In general we encourage you to use web services with the Translator instead of plugins with Iguana 5.0.

Here’s some of the content of an IguanaConfiguration.xml file with highlights over the parts of the file you would need to edit:

<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:/iguanaB/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7001"/>

iguanaC.hdf [top]

This configuration file for the C instance of Iguana supplies the working directory where the IguanaConfiguration.xml and vcs_repo.sqlite files are stored. All relative VMD file paths are based on this directory.

Notice how the explicit path to the Iguana executable is given as C:\IguanaApp\iguana.exe (for non-Windows operating systems /home/iguana/iguana_app/). This is the location of the unzipped application files.

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

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"

IguanaConfiguration.xml C [top]

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

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.

There are three key settings which need to be different from the other 2 Iguana instances:

  1. The web port that the user interface of the Iguana server uses: 8002
  2. The log directory used to store the log files: D:\iguanaC\logs
  3. The plugin port (it’s not essential to change this but if you don’t you will get a error when Iguana starts up): 7002

The plugin port is used for plugins with Iguana. In general we encourage you to use web services with the Translator instead of plugins with Iguana 5.0.

Here’s some of the content of an IguanaConfiguration.xml file with highlights over the parts of the file you would need to edit:

<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:/IguanaC/logs/"
   max_log_age_days="60"
   log_sync_type="full"/>
<rpc_config
   port="7002"/>

Leave A Comment?