Deployment best practices

Introduction

This document outlines best practices for installing Iguana in a manner which:

  1. Makes upgrades easy and risk free.
  2. Keeps it simple to reliably back up your Iguana server.
  3. Simplifies important system administration tasks such a rebuilding a server, patching the operating system and so on.

The key concept here is the separation of concerns by having different directories for Iguana’s:

  1. Application files.
  2. Configuration files.
  3. Logs.

The document assumes you are using Windows but the concepts can be applied to other operating systems. It also assumes an environment that is only running one instance of Iguana per server and the upgrades are done with the entire instance at once.

The key thing is to understand the principles explained, as there is no single solution for all scenarios, please contact support at support@interfaceware.com if you need more help with your installation.

Why is this important? [top]

The default automatic installer of Iguana lumps the Application, Configuration and Log files all together. Which is okay for a non production installation, as we want to make it easy for people who are curious about Iguana to get up and running. But it is not the best practice for a system for a production system.

Anyone can download Iguana and click through the automated installer, but it takes more care to do a professional installation that will be correct for production deployment. To do the job right though takes a little more care than just clicking on the automated installer. It’s about investing a little time and thought up front so you don’t get caught out later.

So let’s go through the advantages of cleanly separating out the parts of Iguana.

Configuration files are valuable and need to be protected

Configuration files are stored in the  Iguana working directory which defaults to the Iguana install directory. For production servers it is best practice to change the working directory to keep the configuration files separated from the log and install files.

Configuration files which include channel configuration, Lua scripts, vmd files for many customers represent intellectual property in which literally hundreds or even thousands of labor hours have been invested. Having these in a separate directory makes it easy to do backups. And makes it easy to rebuild a server if the operating system gets corrupted. It limits the sizes of those backups so that they can be done more frequently. It makes it more transparent and easier for technical people working on the server to troubleshoot when issues occur.

Also keeping configuration files separated from log files is a good idea because logs files are huge, they change much more frequently and so a different kind of backup routine is desirable.

Log files belong on their own partition

Best practice for log files is to store them on a different partition from the from the operating system. Consider if you have an interface which goes rogue. This results in a huge unexpected volume of log data. If the logs are on the same partition as the operating system it can seriously affect the integrity of the server. Also to get the best performance the logs should be placed on the fastest possible partition (or disk device).

Application files should be disposable

As a system administrator you should be able to drop in a new version of Iguana and delete an old version without the slightest bit of worry of losing your configuration files or your log files. That’s why it makes sense to keep application files in their own directory.

Why not just rely on virtual machine snapshots?

It’s tempting to think these things don’t matter when you have virtualized servers that make it easy to roll a server back. But, it’s not an ideal solution because of the lack of separation of concerns.

Some operating systems like Windows do degrade over time. They need to be patched. You periodically need to upgrade to new server OS versions. Sometimes to make windows servers run well the need arises to reinstall from scratch. If you rely on snapshots to manage backups it makes it opaque as to how to rebuild a machine from scratch which is a necessary part of system administration.

If you need to restore an older configuration but you need to keep the logs then it’s harder to do that. Also backing up the entire machine with logs takes a lot more storage, whereas if the configurations are backed up independently it’s a lot easier to store the history for those backups for a longer period of time because the amount of data is much smaller.

Initial Configuration [top]

This is our recommended configuration:

  • Iguana is installed in its own directory:

    We recommend including the version of Iguana in the directory name, like : C:\Program Files\iNTERFACEWARE\Iguana-<version number>\ This means you can upgrade to a new version without overwriting the previous install, an makes it very easy to roll back to a previous version if you need to.

  • Configuration files are stored in a separate working directory:

    For a new install you will need to create a separate working directory, like : C:\Program Files\iNTERFACEWARE\Config\ and then move the configuration files to that directory (see the steps below for more details). You can also move an existing working directory by renaming or copying it (you will also need to update iguana_service.hdf to point to your new working directory).

  • Log files are placed on a separate device or partition:

    To get the best performance the logs should be placed on the fastest possible partition (or disk device). If you are running a small server then the logs should ideally be placed on a dedicated disk (not a separate partition on a shared disk). In a corporate environment you will very likely be allocated space on a SAN or NAS (speak to your system administrator).

Steps for initial configuration:

  1. Install Iguana manually:

    It is easy to get the latest no installer version of Iguana just click the Other downloads are available below link on our iNTERFACEWARE Downloads page, and select the Windows 32 or 64 bit Manual Installer. See Download other install files for all other operating systems and older releases. Then follow the Iguana manual install procedure.

    1. Single Iguana instance on a Server:
      1. Directory: C:\Program Files\iNTERFACEWARE\Iguana-<version number>\
      2. Examples:
        • C:\Program Files\iNTERFACEWARE\Iguana-6-1-1\
        • C:\Program Files\iNTERFACEWARE\Iguana-6-1-2\
        • C:\Program Files\iNTERFACEWARE\Iguana-6-1-3\
    2. Multiple Iguana instances on a Server:
      1. Directories:
        • C:\Program Files\iNTERFACEWARE\Instance_1\Iguana-<version number>\
        • C:\Program Files\iNTERFACEWARE\Instance_2\Iguana-<version number>\
        • C:\Program Files\iNTERFACEWARE\Instance_3\Iguana-<version number>\
      2. Examples:
        1. C:\Program Files\iNTERFACEWARE\Instance_1\Iguana-6-1-1\
        2. C:\Program Files\iNTERFACEWARE\Instance_1\Iguana-6-1-2\
        3. C:\Program Files\iNTERFACEWARE\Instance_2\Iguana-6-1-1\
        4. C:\Program Files\iNTERFACEWARE\Instance_2\Iguana-6-1-2\
        5. C:\Program Files\iNTERFACEWARE\Instance_3\Iguana-6-1-1\
        6. C:\Program Files\iNTERFACEWARE\Instance_3\Iguana-6-1-2\
  2. Stop the Iguana service.
  3. Place the configuration files in a separate working directory:

    You can create the working directory anywhere you like, for example: C:\Program Files\iNTERFACEWARE\Config\ or C:\IguanaConfig\ . However placing the working directory in the same directory as the Iguana install directory works well — as it keeps things logically grouped together. For example if Iguana is installed in C:\Program Files\iNTERFACEWARE\Iguana then you would use C:\Program Files\iNTERFACEWARE\Config.

    1. Single Iguana instance on a Server:
      1. Directory: C:\Program Files\iNTERFACEWARE\Config
    2. Multiple Iguana instances on a Server:
      1. Directory: C:\Program Files\iNTERFACEWARE\Instance_1\Config
      2. Directory: C:\Program Files\iNTERFACEWARE\Instance_2\Config
      3. Directory: C:\Program Files\iNTERFACEWARE\Instance_3\Config
    3. Copy the configuration files from the Iguana installation to the working directory:
      1. Stop the Iguana service if necessary:

        The Iguana service must be stopped before copying the main repository or you risk losing changes, and the copyied repository may be corrupt/incomplete.

      2. Copy the IguanaMainRepo directory to the new working directory, for example:
        • Install Directory: C:\Program Files\iNTERFACEWARE\Iguana
        • IguanaMainRepo: C:\Program Files\iNTERFACEWARE\Iguana\IguanaMainRepo
      3. Copy the Iguana Environment File to the new working directory — if it exists:
        • Environment File: <working directory>/IguanaEnv.txt
  4. Update  iguana_service.hdf to point to the new working directory:
    1. The iguana_service.hdf file is in the Iguana install directory:

      If the Iguana install directory is C:\Program Files\iNTERFACEWARE\Iguana, the you will need to update the C:\Program Files\iNTERFACEWARE\Iguana\iguana_service.hdf file.

    2. Add the the — working_dir “C:\Program Files\iNTERFACEWARE\Config\” option as shown:

      The critical piece of information is the –working_dir argument. This tells Iguana where to get its configuration files from, in this case you can see we are getting them from C:\Program Files\iNTERFACEWARE\Config\.

      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 systems update the command_line_unix=./iguana line in iguana_service.hdf 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:\Program Files\iNTERFACEWARE\Config\"
   command_line_unix=./iguana
   path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
  5. Restart the Iguana Service:

    You can start the Iguana service using the Windows Service control panel. Or if you prefer you can use the windows command to run the net start Iguana and net stop Iguana commands.

  6. You will need to use your members account to activate or transfer a license.
  7. Place Log files on a separate device or partition:

    Place log files for each Iguana instance on a separate partition or device — logs for multiple instances should never share a single device (or performance will suffer).

    1. Single Iguana instance on a Server:
      • Example: D:\IguanaLogs\
    2. Multiple Iguana instances on a Server:
      1. Examples:
        • D:\IguanaLogs\
        • E:\IguanaLogs\
        • F:\IguanaLogs\

Changing the Logs Directory [top]

You can change the directory in which Iguana stores its logging information.

Warning! to change the log directory, you must first stop the Iguana service.

To change the log directory:

  1. Pick a time when your Iguana server is not being heavily used.
  2. Log out of Iguana.
  3. Stop the Iguana service.
  4. Use a text editor to edit the Iguana configuration file IguanaConfiguration.xml. This file is  located in the Iguana configuration repository directory (<working-directory>/IguanaConfigurationRepo/IguanaConfiguration.xml).
  5. In IguanaConfiguration.xml, change the log_directory entry to the location of the directory in which you want Iguana to write its log files.
    Note: The Iguana service user must have read and write permission for this directory, or Iguana will not run.
  6. Save and close IguanaConfiguration.xml.
  7. Make a backup copy of the log directory.
  8. Move or copy the files from the old log directory to the new log directory.
    Note: If you copy the files you can use the original copy as your backup.
  9. Restart the Iguana service and log back into Iguana.

Upgrading an Iguana Instance [top]

Upgrading an Iguana instance that has been professionally configured as above is an easy 15 minute process. Before you start it though you should check the ‘maintenance expiry’ date on your instance of Iguana. You might need to ask iNTERFACEWARE to refresh this license key if the date is less than the date that the new version of Iguana that you are installing was released. See How to fix an invalid licence after an upgrade.

  1. Download a no installer zip file for the new version of Iguana. Make sure you pick the right operating system and 32 vs. 64 build etc.
  2. Extract the zip into a fresh new versioned folder., like: C:\Program Files\iNTERFACEWARE\Iguana-6-1-2\
  3. Replace the iguana_service.hdf file with the following contents: 
    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
}
  4. Use the command line console to change directory into the folder you extracted the files into.
  5. Then run the command: iguana_service --install
  6. This will stop the existing service and replace it with the new service.
  7. You must restart the Iguana service now to begin running the new version of Iguana.
  8. Login into the Iguana dashboard and verify that the channels are running correctly that should be running.

The beauty of this process is that it doesn’t take long and it’s really easy to roll back to an older copy of Iguana. The rollback process is even easier if you keep the service_name parameter as it’s default value of “Iguana”.

Rolling back to an older version [top]

Rolling back to an older version of Iguana is a very similar process to that described above (in Upgrading an Iguana Instance).

  1. Use the command line to change into the application directory of the current Iguana version.
  2. 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).

  3. Use the command line to change into the application directory of the older Iguana version to rollback to.
  4. Run the command: iguana_service --install
  5. Restart the Iguana service using the Services control panel or using net start Iguana at the command line.
  6. 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).

Troubleshooting [top]

One of the great things about this process of installation is that it makes things very transparent and easy to troubleshoot. If the Iguana service does not start then one can see what is going on by running Iguana as a console process and looking at its output. It’s easy.

To do it change into the Iguana application directory and run it like this:

iguana --run --working_dir C:\Program Files\iNTERFACEWARE\Config\

This is a great way to diagnose problems such as Iguana not being able to listen on a given webport, issues with log files and so on. I would recommend it as a technique for any Iguana system administrator as a means of validating each stage of an installation or upgrade.

See troubleshooting for more information.

Helpful Tips [top]

Disabling Auto-Start of Channels.

Sometimes during upgrades it can make sense to turn off auto-starting of all channels. There is a helpful screen you can do this from, called the Channel Properties screen.

Extracting Configuration Files from an Existing Iguana Installation.

If you have inherited an existing Iguana installation that has everything in one directory you will need to create a working directory and copy the configuration files into it. This is very simple just follow the initial configuration steps for creating a working directory and copying the configuration files.

License keys

License keys for Iguana are keyed off the working directory. So if you change the working directory you will need a new license key. However if you do not, then this is not necessary.

Deleting old Iguana versions

This is not strictly necessary, but it is easy to do when you are happy no rollback is required. Just delete the contents of the directory which contain the application files. It’s easy when you have only application files in the Iguana application directory.

More Information [top]