Manual installation Best Practices


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 IguanaConfiguration.xml D:\iguanaA\logs\ 8000 7000
B IguanaConfiguration.xml D:\iguanaB\logs\ 8001 7001
C IguanaConfiguration.xml D:\iguanaC\logs\ 8002 7002

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. Only Iguana 5.0 and up support the Global Dashboard however.

If you have any questions please let us know.

Leave A Comment?