Creating a preconfigured Iguana install

Customize an Iguana install

Note: This article was originally written for Iguana 5, which uses fossil for source control. The aritcle describes how to create a fossil repository, this will need to be changed to create an equivalent Git repository if you need help with this please contact us at

While we never white box license Iguana, it is often desirable to deliver Iguana already fully preconfigured to run out of the box, or partially preconfigured to give end-users a head start towards their final use.

Only two files are involved in creating a custom configuration: IguanaConfiguration.xml and vcs_repo.sqlite. The vcs_repo.sqlite file is new since version 5.0 of Iguana. It stores the Lua source code for the Translator channels.

The easiest way to create a custom installation is to start from a downloaded zip archive intended for manually installing Iguana and modify it to include the specific configuration you want. The modified zip archive can then be extracted into a directory of choice ready to be executed by a simple “iguana –run” command.

Tip: You can easily create an installer that installs the latest version of Iguana and then applies the desired changes (by updating IguanaConfiguration.xml and vcs_repo.sqlite).

See How to automatically install the latest version of Iguana


  • By altering the zip file so that it comes with your own specialized IguanaConfiguration.xml and Fossil repository (vcs_repo.sqlite), a vendor can have Iguana preconfigured to use their own specific configuration.
  • Vendors will usually be advised to either ship a vcs_repo.sqlite file, which means that their install will always overwrite any current install, or the initial.sqlite repository, which is copied by Iguana if vcs_repo.sqlite is not found.
  • The simplest way to create a vcs_repo.sqlite file is just to copy it from a existing copy of Iguana that has the desired configuration. It is possible to extract files from a Fossil repository and then create a fresh repository without having all of the history of those files.

It’s possible to work out the details of how to create a custom install, from basic principles, using the information on these pages and other pages in our present manual. But this topic seems to interest a lot of vendors, so watch this page. More details will follow.

We don’t whitebox Iguana [top]

We never white box license Iguana. This simply makes no sense for the product. That would be like buying a Lexus and taking it home and spraying ‘bob’s motor car’ on the side. Amusing I guess but it does not help to position your own brand as a good solution.

Hospitals trust vendors who use Iguana more than those who have home grown integration solutions. Iguana technology is deployed at well over 10,000 installs and most North American health data centers have multiple instances supplied by many different partners as part of their solutions.

Create a default installation [top]

Follow the steps outlined in Manual Install section to download and extract Iguana. After completing the steps, the Iguana will be in a clean state without any configuration files present.

From the command line, enter iguana –run. This command will create IguanaConfiguration.xml file in the same directory in which Iguana was installed. It will also create vcs_repo.sqlite by making a copy of the existing file named initial.sqlite. If initial.sqlite is not present, a blank repository will be created.

If you encounter any problems in this step, consult the Installation section.

You can now use the created files (IguanaConfiguration.xml and vcs_repo.sqlite) as the basis for creating a custom installation.

Adding a shared library [top]

Just follow these four simple steps:

  1. Create a channel to use as an example. The name of the channel will be used in the drop-down list when importing.
  2. Add a shared module (lets call that new module SM). Add source code to the module.
  3. Add require 'SM' to the module mail. Commit a milestone. The repository will now contain a new example that uses SM shared module.
  4. Rename the vcs_repo.sqlite to initial.sqlite and add it to the zip file containing manual Iguana install.

Note: if you also want to ship IguanaConfiguration.xml, you might want to remove the channel so it does not show up in the dashboard. This has to be done directly from the two places in IguanaConfiguration.xml, rather then from the dashboard. If done from the dashboard, the source will also be removed from the repository, and become invisible on import.

Creating an initial repository from scratch [top]

In this example, we will use both Iguana and standalone fossil executable to create a repository file with our own set of examples.

  1. Create a new Iguana working directory my_working_dir. Run iguana with ‘iguana –run –working dir my_working_dir
  2. Create a channel that you want to use an example. The name you give to the channel will be shown in the list of existing projects when importing.
  3. Edit the script. Add any required shared modules and other support files (such as VMD’s)
  4. When you are ready to add the channel to a repository, copy my_working_dir/edit/<user name> into a temporary directory (tmp_dir).
  5. Remove tmp_dir/_FOSSIL_
  6. From within the tmp_dir, do the following set of commands:
    1. fossil new initial.sqlite
    2. fossil open initial.sqlite
    3. fossil add <CHANNEL_GUID>
    4. fossil add shared
    5. fossil add other
    6. fossil commit -f -m “My Initial Revision Name” –tag “My Example Name”
    7. fossil close
      Note: The CHANNEL_GUID is a 32 character hexadecimal ID unique for each channel. The mapping from channel names to GUIDs can be observed in IguanaConfiguration.xml.
  7. Add initial.sqlite to your Iguana manual installation zip file. If initial.sqlite already exists inside the zip file, remove it first.

Working outside the install directory [top]

For a vendor who wants to be particularly rigorous, it’s even possible to cleanly separate the Iguana application files from their own configuration files. It makes sense to do this and to separate the log files into their own directory. For example:

  1. Iguana Application Dir
  2. Configuration Files (Fossil Respository + IguanaConfiguration.xml)
  3. Logs

To create this separation:

  • To change the log directory edit the configuration file IguanaConfiguration.xml.
    • Usually in the install directory (eg: C:Program FilesiNTERFACEWAREIguana).
    • Change the log_directory entry to the new log directory.
  • To specify the configuration file directory edit the file iguana_service.hdf .
    • Usually in the install directory (eg: C:Program FilesiNTERFACEWAREIguana).
    • Windows: change the command_line entry, use the –working_dir parameter to specify the directory:
      • command_line=iguana.exe --working_dir "D:buildv5"
    • Unix, Linux or Mac OS X: change the command_line_unix entry:
      • command_line_unix=./iguana --working_dir "Users/admin/build/v5"
  • You will need to restart Iguana to pick up the changes.

How to automatically install the latest version of Iguana [top]

You can create a Windows installer that will automatically install the latest version of Iguana, and then apply your desired configuration. To help you do this we have created the permanent links to the latest version of the Iguana installers and zip files.

  1. Use the appropriate permanent link to download an installer or zip:
  2. Run the downloaded installer or unpack the zip
  3. Apply your desired changes (by replacing IguanaConfiguration.xml and vcs_repo.sqlite)

Leave A Comment?