Upgrade to Iguana 6

Introduction

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. In general 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. Copy the vcs_repo.sqlite file from your version 5 installation into the new install directory.
  9. 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):
      • Identify the source working directory: View the version 5 iguana_service.hdf file and look for an iguana.exe --working_dir “IguanaConfig” entry — if it exists then the source working directory = “IguanaConfig”, otherwise the working directory is the install directory (default).
      • Copy from the source working directory: <working directory path>\IguanaConfiguration.xml
      • Copy to the target working directory: <version 6 install path>\IguanaConfiguration.xml

        Warning: If you are following the order of the steps in this procedure then the target working directory will always be the <version 6 install path>

        However if you already changed the working directory by modifying the iguana_service.hdf file — then you must use your updated value as the target working directory.

        Note: In this procedure we actually modify the working directory in the next step (step 9) after updating the IguanaConfiguration.xml file — to simplify the procedure.

    • 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. If your license is not recognized you can get a seven day temporary license — please choose a Standard license.

    Warning: Do not upgrade to an Enterprise license at this time, see the last step in this procedure.

    Changing to an Enterprise license requires that you setup Iguana encrypted logs — it is better to do this process separately.

  15. If the old version of Iguana is still showing in the browser, then use F5 to refresh the browser cache.
  16. 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.
  17. 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
  18. 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
  19. 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)
  20. 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)
  21. 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
  22. Close the command prompt window
  23. Follow the log encryption Upgrade Procedure to upgrade to an Iguana 6.1.X Enterprise License.

    For more information about log encryption please read the articles in the Log Encryption section.

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. Copy the vcs_repo.sqlite file from your version 5 installation into the new install directory.
  12. 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
  13. 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
  14. 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.
  15. 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
  16. If your license is not recognized you can get a seven day temporary license.

    Warning: Do not upgrade to an Enterprise license at this time, see the last step in this procedure.

    Changing to an Enterprise license requires that you setup Iguana encrypted logs — it is better to do this process separately.

  17. If the old version of Iguana is still showing in the browser, then use F5 to refresh the browser cache.
  18. 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.
  19. 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
  20. Install the Iguana daemon:
    Note: Do not perform this step if your version 6 service settings are unchanged from version 5.

  21. Start the Iguana daemon, run a command like this:
    <home>/iNTERFACEWARE-Iguana/iguana_service
    <home>/iNTERFACEWARE/Iguana-6-0-1/iguana_service
  22. 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)
  23. Uninstall the previous version 5 Iguana:
    Note: You do not need to uninstall 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)
  24. Close the terminal window.
  25. Follow the log encryption Upgrade Procedure to upgrade to an Iguana 6.1.X Enterprise License.

    For more information about log encryption please read the articles in the Log Encryption section.

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.
Tagged: