Upgrade to Iguana 6

Upgrading from Iguana 5 to Iguana 6 is much like any other upgrade, with one exception. When Iguana starts for the first time it needs to convert the repository from Fossil to Git.

This means that when Iguana starts for the first time it will take longer. For most servers it will just be a few seconds, and you probably won’t even notice. The upgrade time Is proportional to the size of the fossil repository, for example upgrading a 30 MB Fossil repository can take up to 5 minutes, depending on hardware. This will mostly affect busy development servers because they have lots of channels and lots of milestones, and therefore large fossil repositories.

To get feedback when upgrading you can run Iguana as a program (not as a service or daemon), by running it using a command prompt or terminal window.

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

Windows Upgrade Procedure [top]

  1. Use an account with Local Administrator privileges.
  2. Download the manual install (zip) file for the latest Iguana release.
  3. Identify the install directory of the Iguana 5 Instance that you are going to upgrade.
  4. Backup the Iguana 5 installation (Iguana 5 documentation)
    Note: This step is optional for non-critical servers.
  5. Rename the original install directory for the Iguana 5 Instance. This step is only required if you wish to install Iguana 6 in the same directory that you used for iguana 5.
    Note: Renaming of the install directory is only required when you are not using versioned install directories.

    • Keeping a (renamed) copy of the previous install directory makes it easy to rollback to version 5, just delete (or rename) the upgraded directory and rename the copy.
    • Useful for upgrade problems, and testing upgrade procedures.
  6. Create a new empty install directory for version 6
    • Recommended best practice: Name the install directory according to match the version of Iguana you are installing, something like:
      C:\Iguana-6-0-1\ or C:\Program Files\Iguana-6_0_1\
      (C:\<install path>\Iguana-<version number>\)

      Tip: Keeping versioned install directories makes it much easier to rollback to a previous version of Iguana.

    • You may may install Iguana 6 in any directory (that grants write permissions to the Iguana service) if you prefer, for example the default Windows install directory is:
      C:\Program Files\iNTERFACEWARE\Iguana\
  7. Unpack the zip file into the new (empty) install directory:
    Note: You can unpack the zip file elsewhere and then copy the files into the install directory.
  8. Update the Iguana configuration:
    Note: If you are upgrading a system that uses the default install settings then no update is required

    • Copy the IguanaConfiguration.xml file from your version 5 installation (overwriting the default file)
      • Copy from: <version 5 install path>\IguanaConfiguration.xml
      • Copy to: <version 6 install path>\IguanaConfigurationRepo\IguanaConfiguration.xml
    • Alternatively: You can update the new version 6  IguanaConfiguration.xml file using a text editor (like notepad):
      • Change the log_directory to the full file path of the original IguanaLogs directory.
        Note: If file path includes spaces then you must use quotes around the file path
      • Save the IguanaConfiguration.xml file
  9. Update the Iguana Service configuration:
    Note: If you are upgrading a system that uses the default install settings then no update is required

    • Copy the iguana_service.hdf file from your version 5 installation
      • Copy from: <version 5 install path>\iguana_service.hdf
      • Copy to: <version 6 install path>\iguana_service.hdf
    • Alternatively: You can update the new version 6 iguana_service.hdf file using a text editor (like notepad):
      • Change the command line value to iguana.exe –working_dir “IguanaConfig file path”. This should be the file path of the original IguanaConfig folder that you created
    • We also recommend changing the service name to reflect the version of Iguana you are running, something like: Iguana_6_0_1
    • Save the iguana_service.hdf file
  10. Run Iguana for the first time in safe mode using a command prompt (do not run as a service).
    Note: This step is optional for non-critical servers.

    • Open a Windows command prompt (do not use Windows PowerShell)
    • Navigate to the new Iguana 6 install directory
    • Run this command:
      iguana --run --safe_mode --working_dir <IguanaConfig file path>

      • --run = run Iguana
      • --safe_mode = do not start any channels that are set to start automatically
      • --working_dir  = set the Iguana Config directory
    • Do not close the command prompt window until you have completed the upgrade procedure
    • Recommended for production servers, and servers with large fossil repositories
    • This will give feedback on the progress of converting the repository from Fossil to Git
  11. Monitor the command prompt output to ensure:
    • No fatal errors occur
    • The blinking cursor line does not reappear
    • The Fossil repo is recognized, backed up, and a new Git repo is built
    • The line “The main event loop is now running” appear (indicating that Iguana has started)
    • Do not close the command prompt window
    • Note: If there are any problems rollback to version 5 and then contact us at support@interfaceware.com for help
  12. Login to Iguana using your user and password (default: user = admin and password = password).
    • Navigate to localhost:<web_config port number>
      Note: The port number is stored in the web_config setting in the IguanaConfiguration.xml file.
    • This should bring you to the login page for your new Iguana 6.x installation.
    • Login using the same credentials as the previous Iguana 5 installation
  13. If your license is not recognized you can get a seven day temporary license.
  14. If the old version of Iguana is still showing in the browser, then use F5 to refresh the browser cache.
  15. Open the Iguana Dashboard and check that your channels exist, your logs look correct and perform any other sanity checks you wish to do.
    Note: For more thorough checking suggestions see the Upgrade Checklist.
  16. You can now stop Iguana program (in the command prompt window):
    • In the command prompt window, terminate the process by typing: Ctrl+C
    • The Iguana process will receive the stop signal, which allows it to stop gracefuly
    • Wait until the blinking cursor is back, which indicates Iguana has stopped
    • Do not close the command prompt window
    • Note: If there are any problems rollback to version 5 and then contact us at support@interfaceware.com for help
  17. Install the Iguana Service (using the command prompt window):
    Note: Do not perform this step if your version 6 service settings are unchanged from version 5 (if the iguana_service.hdf file is unchanged)

    • Open a command prompt if required
    • Navigate to the new Iguana 6 install directory
    • Run this command:
      iguana_service -- install
    • Do not close the command prompt window
  18. Start the Iguana service:
    • Open Windows Service Manager
    • Start the new Iguana Service
    • Check that Startup Type is Automatic (so that Iguana starts automatically when the server starts)
  19. Check that Iguana is running
    • Login to Iguana
    • Check that Iguana version 6.x is running
    • Note: As a precaution you can check that things like channels and logs look correct (like you did in step 15 above)
  20. Uninstall the previous version 5 Iguana:
    Note: You do not need to do this immediately (you might prefer to keep the old version for a few weeks in case it is needed for troubleshooting)

    • Open a command prompt if required
    • Navigate to the previous Iguana 5 install directory
    • Run this command:
      iguana_service -- uninstall
      Note: If you decide to keep the old service we strongly recommend disabling it so it cannot be started by accident
    • Backup the previous Iguana 5 install directory
    • Delete the previous Iguana 5 install directory (unless you are keeping the the version 5 install for troubleshooting)
      Note: Make sure you uninstall the version 5 Iguana service before deleting the install directory
  21. Close the command prompt window

Mac or Linux Upgrade Procedure [top]

  1. Download the latest Iguana release for your operating system.
  2. Identify the install directory of the Iguana 5 Instance that you are going to upgrade.
  3. Backup the Iguana 5 installation (Iguana 5 documentation)
    Note: This step is optional for non-critical servers.
  4. Make a complete copy of the install directory for the Iguana 5 Instance.
    • This makes it easy to rollback to version 5, just delete (or rename) the upgraded directory and rename the copy.
    • Useful for upgrade problems, and testing upgrade procedures.
  5. Run Terminal.
  6. Create a new empty install directory for version 6

    • Recommended best practice: Name the install directory according to match the version of Iguana you are installing, something like:
      <home>/iNTERFACEWARE/Iguana-6-0-1\ or <home>/iNTERFACEWARE/Iguana-6_0_1\
      (<install path>/iNTERFACEWARE/Iguana-<version number>\)

      Tip: Keeping versioned install directories makes it much easier to rollback to a previous version of Iguana.

    • You may may install Iguana 6 in any directory (that grants write permissions to the Iguana daemon) if you prefer, for example the default Mac/Linux install directory is:
      <home>/iNTERFACEWARE-Iguana
  7. Browse to the download directory:
    cd <download directory>
  8. Unpack the tarball into the iNTERFACEWARE-Iguana directory:
    tar -xvzf <downloaded install file name>.tar.gz
  9. Copy the unpacked files into the new (empty) install directory.
  10. Browse to the install directory,for example:
    cd <home>/iNTERFACEWARE-Iguana
    cd <home>/iNTERFACEWARE/Iguana_6_0_1
  11. Update the Iguana configuration:
    Note: If you are upgrading a system that uses the default install settings then no update is required

    • Copy the IguanaConfiguration.xml file from your version 5 installation (overwriting the default file)
      • Copy from: <version 5 install path>\IguanaConfiguration.xml
      • Copy to: <version 6 install path>\IguanaConfigurationRepo\IguanaConfiguration.xml
    • Alternatively: You can update the new version 6 IguanaConfiguration.xml file using a text editor:
      • Change the log_directory to the full file path of the original IguanaLogs directory.
        Note: If file path includes spaces then you must use quotes around the file path
    • Save the IguanaConfiguration.xml file
  12. Run Iguana for the first time in safe mode in the terminal window, (not as a service or daemon).
    Note: This step is optional for non-critical servers.

    • Open a new terminal window if required
    • Navigate to the new Iguana 6 install directory
    • Run this command:
      ./iguana --run --safe_mode --working_dir <IguanaConfig file path>

      • --run = run Iguana
      • --safe_mode = do not start any channels that are set to start automatically
      • --working_dir = set the Iguana Config directory
    • Do not close the terminal window until you have completed the upgrade procedure
    • Recommended for production servers, and servers with large fossil repositories
    • This will give feedback on the progress of converting the repository from Fossil to Git
  13. Monitor the command prompt output to ensure:
    • No fatal errors occur
    • The blinking cursor line does not reappear
    • The Fossil repo is recognized, backed up, and a new Git repo is built
    • The line “The main event loop is now running” appear (indicating that Iguana has started)
    • Do not close the terminal window
    • Note: If there are any problems rollback to version 5 and then contact us at support@interfaceware.com for help.
  14. Login to Iguana using your user and password (default: user = admin and password = password).
    • Navigate to localhost:<web_config port number>
      Note: The port number is stored in the web_config setting in the IguanaConfiguration.xml file.
    • This should bring you to the login page for your new Iguana 6.x installation.
    • Login using the same credentials as the previous Iguana 5 installation
  15. If your license is not recognized you can get a seven day temporary license.
  16. If the old version of Iguana is still showing in the browser, then use F5 to refresh the browser cache.
  17. Open the Iguana Dashboard and check that your channels exist, your logs look correct and perform any other sanity checks you wish to do.
    Note: For more thorough checking suggestions see the Upgrade Checklist.
  18. You can now stop Iguana program (in the terminal window):
    • In the command prompt window, terminate the process by typing: Ctrl+C
    • The Iguana process will receive the stop signal, which allows it to stop gracefuly
    • Wait until the blinking cursor is back, which indicates Iguana has stopped
    • Do not close the terminal window
    • Note: If there are any problems rollback to version 5 and then contact us at support@interfaceware.com for help
  19. Install the Iguana daemon:
    Note: Do not perform this step if your version 6 service settings are unchanged from version 5.

  20. Start the Iguana daemon, run a command like this:
    <home>/iNTERFACEWARE-Iguana/iguana_service
    <home>/iNTERFACEWARE/Iguana-6-0-1/iguana_service
  21. Check that Iguana is running
    • Login to Iguana
    • Check that Iguana version 6.x is running
    • Note: As a precaution you can check that things like channels and logs look correct (as you did in step above)
  22. Uninstall the previous version 5 Iguana:
    Note: You do not need to unisnstall immediately (you might prefer to keep the old Iguana installation for a few weeks in case it is needed for troubleshooting)

    • Edit crontab and delete (or comment out) the Iguana 5 entry — to prevent the version 5 Iguana daemon from starting
    • Backup the previous Iguana 5 install directory
    • Delete the previous Iguana 5 install directory (unless you are keeping the the version 5 install for troubleshooting)
  23. Close the terminal window

iguana --run feedback [top]

This shows the feedback from upgrading an Iguana 5 server on a Mac, the results will be very similar on other operating systems. In this case the upgrade only took two seconds, but it can take considerably longer for servers with large fossil repositories.

Upgrade Checklist [top]

  1. Go to the Iguana Dashboard
  2. Check that all of your channels are present
  3. Check that the Iguana logs are present:
    • Open the Iguana Logs
    • Inspect the logs to ensure everything looks correct
  4. Check that channel auto-start settings are correct
    • Open the Channel Properties page
    • Ensure that Start Automatically is checked for the channels you are using
    • Note: You can also set the logging level in the properties page
  5. Perform any other sanity checks relevant to you installation, like:
    • Verify user and role settings
    • Check environment variables
    • Verify remote server connections
    • Other mission critical items
  6. Finally you may need to update channel code if any processing errors occur.

    Note: If your system followed the best practices for manual installation of Iguana, then file structures will have been maintained and code changes should not be necessary.

    Warning: Do not attempt to make code changes directly on a production server — even if they seem trivial.

    If you notice processing errors stop the channel and make the necessary  changes on a dev (or test) server and then release them to the production server when they are ready.

Rollback to Iguana version 5 [top]

Rolling back to version 5 is slightly different from the usual rollback procedure as it reverts back to using the fossil repository (it actually makes it slightly easier as you do not need to restore the previous git repository).

For Windows:

  1. Stop the Iguana 6 service.
  2. Disable the Iguana 6 service.
  3. Rename the Iguana 6 directory.
    Note: This step is not required if you are using versioned install directories
  4. Rename the Iguana 5 directory to its original name.
    Note: This step is not required if you are using versioned install directories
  5. Enable the Iguana 5 service.
    Alternatively recreate the iguana 5 service if it does not exist:

    • Open a Windows command prompt (do not use Windows PowerShell)
    • Navigate to the Iguana 5 install directory
      Run this command:
      iguana_service -- install
  6. For development or test servers only!
    You may also decide to restore the backup copy of the log directory (backed up during the upgrade procedure).

    Note: This might be appropriate when you are testing the upgrade on a dev or test server (though keeping the log data could be useful to debug any issues).

    Warning: Never do this on a Production Server as the logs keep a legal record of processed data.

  7. Start the iguana 5 service.
  8. Open Iguana in the browser and ensure stability of the previous version.

For Mac/Linux:

  • Stop the Iguana 6 daemon.
  • Edit crontab and delete (or comment out) the Iguana 6 entry — to disable the Iguana 6 daemon.
  • Rename the Iguana 6 directory.
    Note: This step is not required if you are using versioned install directories
  • Rename the Iguana 5 directory to its original name.
    Note: This step is not required if you are using versioned install directories
  • Add a crontab entry to enable the Iguana 5 daemon.
  • For development or test servers only!
    You may also decide to restore the backup copy of the log directory (backed up during the upgrade procedure).

    Note: This might be appropriate when you are testing the upgrade on a dev or test server (though keeping the log data could be useful to debug any issues).

    Warning: Never do this on a Production Server as the logs keep a legal record of processed data.

  • Start the iguana 5 daemon.
  • Open Iguana in the browser and ensure stability of the previous version.

Leave A Comment?