See the Best Practice Production Deployment for Iguana article in our Deployment Guide section.

Issue

If the Maintenance Expiry Date for the license has expired, then the server will not start after the upgrade. Therefore it can be useful to check before upgrading.

To solve this issue

1. Check the Maintenance Expiry Date in Settings > License Entitlement:
   If the date is less than the the current date your server would not work after an upgrade (until a new license is obtained).
   
2. Contact support at support@interfaceware.com with your Iguana ID and request an updated license code with a more recent date.

Issue

Occasionally after an upgrade the Maintenance Expiry Date for the license will show as expired, and the server will not start.

To solve this issue

1. Check the Maintenance Expiry Date in Settings > License Entitlement:
   If the date is less than the the current date your server will not work until a new license is obtained.
   
2. Log into your user account and activate a temporary license to regain access to the software.
3. Then contact support at support@interfaceware.com with your Iguana ID and request an updated license code with a more recent date.

Issue

You have a valid Iguana License. However after an upgrade using the Windows automatic installer, a new Iguana ID is generated and you are requested to enter a new registration code.

This occurs if the installer does not recognize Maintenance Expiry Date updates, and therefore enforces the original license expiry date. Perceiving that you are now operating without a valid license, the installer issues a new Iguana ID and inadvertently locks you out of the software.

To solve this issue

1.  Log into your user account and activate a temporary license to regain access to the software.
2. Then contact support at support@interfaceware.com with your Iguana ID and request an updated license code with a more recent date.

There are two options: Separate install directory, or Shared install directory and separate working directory

Separate install directory

Use the manual installation process and install each instance in a separate directory. This is the simplest setup, it’s good for a development and testing where you want to the flexibility to run different versions of Iguana.

• Advantage: Less planning required to create multiple Iguana Instances
• Advantage: Easier to add/remove Iguana Instances
• Advantage: You can use several different versions of Iguana
• Disadvantage: You need to upgrade each install separately
• Disadvantage: Duplicate install directories use slightly more disk space

Shared install directory

Create a common install directory and use separate working directories, see Manual installation Best Practices. This setup requires a little planning, it is good for a production environment where you need to ensure all your Iguana Instances are using the same  version.

• Advantage: All Iguana Instances will use the same version
• Advantage: All instances are upgraded together
• Advantage: A single install directory use slightly less disk space
• Disadvantage: More planning required to create multiple Iguana Instances
• Disadvantage: Harder to add/remove Iguana Instances

From Iguana 4.0 onwards all the configuration files were consolidated into a single configuration file called IguanaConfiguration.xml. For Iguana 3.3.2 there were 3 configuration files:

• ChannelConfiguration.xml: Stored the channel configuration, email server and HTTPS server settings
• AdminConfiguration.xml: Stored the HTTP web server settings, e.g., default port used
• UserConfiguration.xml: Stored the username and password information

We invested a lot of effort in providing a smooth migration path for Iguana 3.x users to migrate these configurations to 4.0 and above. The trick to leveraging this effort with a manual Iguana installation is to:

1. Do a manual install of Iguana 5.x.
2. Make sure the Iguana 5.x service is stopped.
3. Delete the IguanaConfiguration.xml file it exists.
4. Copy all 3 of the above legacy configuration files from your Iguana 3.x instance into the working directory of the Iguana 5.x instance.
5. Edit the files so that:
   • A different web server port is used.
   • None of the channels are configured to start automatically.
6. Start Iguana. I usually prefer to start it from the command-line using iguana.exe --run and closely observe the log output to make sure it found the legacy files and converted them.

By default what Iguana 4.0 and onwards does is that when it starts up, if it cannot find the IguanaConfiguration.xml file in it’s working directory, then it looks for the presence of the legacy configuration files. It will then convert the contents of these files into a new IguanaConfiguration.xml file and move these older configuration files out of the way.

Sometimes you hear about features which are not in the formally released version of Iguana. That doesn’t mean you have to wait before you can try them out yourself.

It’s helpful to understand how we manage our builds.

When we develop new features they usually are put into the “head” or “unstable branch” of Iguana. This is because while these features are “under construction” they may result in bugs and other side effects. The “unstable branch” occasionally will get broken but it always has the newest set of features that are under development.

When features look mature enough, the changes get promoted into the “stable branch” of Iguana. This is what will become the next incremental release of Iguana, as delimited by the minor version numbers. The “stable branch” snapshot is much less bleeding edge.

Obviously the “unstable branch” snapshots should not be put into mission critical production environments, although you can often get away with using them in development so long as you are willing to test a little with your production release before deploying.

We make these snapshots publicly available. These are rebuilt and uploaded to our public download site every day. The help center download page has links to the automatic installer and manual install files for both branches. Enjoy.

We sometimes get questions from customers about our development process.

When you are installing multiple instances of Iguana (as windows services) on a single server, you need to ensure that each instance uses a different service name. Before installing the service (using iguana --run) you need to change the the service_name and (optionally) the service_description (easier to differentiate between services). If you do not change the service name you will overwrite any existing service with the same name.

The iguana_service.hdf file that the iguana_service.exe file will load up (iguana_service.exe is bootstrap program responsible for invoking the main iguana.exe as a service). Under Windows it defines how the service will appear in the Services window.

Some key parameters:

• service_name: the name of the service. Pick something like “Iguana5”. Then net start Iguana5 can be used to start the service.
• service_description: how the service is described in the service window. Useful for putting in more descriptive information.
• command_line: This is useful for including special flags to be passed to the main Iguana executable like --working_dir <dir-name>

It is important to change the service_name otherwise another Iguana service entry can be overwritten. Ideally you should also change the service_description to easily differentiate between services.

The other parameters typically do not need to be altered:

application{
   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana
   service_name=Iguana
   service_description=HL7 Integration Engine
   command_line=iguana.exe
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEMCurrentControlSetControlSession ManagerEnvironment
}

This can occur when you are installing multiple instances of Iguana on a single machine (particularly for the first time). Don’t panic it is very simple to fix!

It’s possible that you might make this mistake:

1. You start off with an Iguana instance installed by the automatic installer at say “C:\Program Files\iNTERFACEWARE\Iguana\”
2. But overwrite the service entry by doing a manual installation of Iguana without editing iguana_service.hdf to change the service name.
   For more information see the FAQ: “How to change Iguana Service details in the iguana_service.hdf file”.

Now what you will see is only one Iguana service registered, but it will be the new Iguana not the old instance.

Your old Iguana instance is still there. All you need to do is:

1. Use the command prompt to do cd “C:\Program Files\iNTERFACEWARE\Iguana\” or wherever your original Iguana was installed.
2. Run iguana_service –install

That will restore your original service. Then:

1. Use the command prompt to cd back into the directory of your new manually installed Iguana.
2. Edit the iguana_service.hdf to change the service name to be something different from the first install.
3. Register it as a service using iguana_service --install

That should leave you with two independent Iguana services.

The IguanaConfiguration.xml file is usually located in the Iguana install directory. To change settings simply open the file in a text editor and change the desired settings. As a precaution it is wise to make a backup copy of the file first.

command_line=C:\IguanaApp\iguana.exe --working_dir "C:\Program Files\iNTERFACEWARE\Iguana\IguanaDev" -- path quoted because it has spaces
command_line_unix=/home/iguana/iguana_app/iguana --working_dir /home/iguana/dev/

The most commonly edited setting are:

• The web configuration port: The “port” attribute in the <web_config> element
• The log directory: The “log_directory” attribute in the <log_config> element
• The plugin port: The “port” attribute in the <rpc_config> element

<iguana_config
 encryption_key="Xb9+OWCgTi3NSSUY2UTGJg=="
 major_version="5"
 minor_version="0"
 build_number="7"
 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"/>

To move or copy Iguana working directory:

1. Make sure that all the unsaved files are saved to milestones.
2. Move (or copy) the working directory to a new location.
3. Go to the new location and erase the edit sub-directory.
4. Different actions are required for moving or copying the working directory
   • Moving: Update the command_line entry in Iguana service/daemon file (iguana.hdf) file to reflect the new working directory:
     command_line=iguana.exe --working_dir <new-dir-name>
   • Copy: Usually you would be copying to a new (or different) Iguana Instance, you will need to update the appropriate target service/daemon file, e.g., iguana.hdf in another install directory (or another machine), or possibly iguanaA.hdf/iguanaB.hdf./iguana<your-name>.hdf if you are running multiple “shared install” instances ( see Manual installation Best Practices for an example of how “shared install” works).