1.2 - Install Guides

Installation guides for Appvance IQ on Windows, Mac, Linux, and cloud platforms.

Windows Installation Guide for AIQ (GraalVM 11 Based)

This is a step-by-step guide for installing and configuring Appvance IQ on Windows.

Windows Installation Guide for AIQ (GraalVM 11 Based)

Installation Prerequisites

Install Preparation Checklist

Please ensure all preparation checklist items are completed and verified prior to install.

Your Appvance contact is always available and more than willing to help with any questions or issues. We recommend confirming the check list at least one business day prior to your scheduled install date, or more depending on your corporate timeframes for resolving permission issues.

Summary Install Preparation Checklist

After you have read the prerequisites, proceed to the next step: Anti-Virus Settings

Windows Installation Guide for AIQ (GraalVM 11 Based)

Anti-Virus Settings

The Appvance IQ installation package is sizable and the vast majority of the contents will never change between installations or upgrades. Because of this, you can exclude the AIQinstallation folder the from the scheduled daily / weekly / monthly scans. Doing so will reduce the time and resources devoted to these scans. Also if these folders are not excluded, you may see some unexpected behavior in AIQ.

For example, this may impact scenario executions, specially on DS and DS3 engines that write many temporary files for requests and responses.

Following are some of the top Anti-virus programs from which the files and folders of Appvance IQ should be excluded:

See McAfee slows down Appvance IQ (Windows) for specific recommendations for McAfee.

After you have configured your anti-virus software, proceed to the next step: Install and Configure GraalVM 11

Windows Installation Guide for AIQ (GraalVM 11 Based)

Install and Configure GraalVM 11

Appvance requires GraalVM 11 to be installed on the controller machine in order to run Appvance IQ. GraalVM is a JDK (Java Development Kit) that is designed to accelerate the execution of applications written in Java and other JVM languages.

For instructions on installing GraakVM on Appvance Test Nodes, see Appvance IQ Manual Test Designer Install (GraalVM 11 Based).

The release notes for GraalVM can be found on the GraalVM site.

Download and Install GraalVM Version 11

  1. GraalVM 11 can be downloaded from https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.0.
  2. Download the Java 11 based Windows installer.
    GraalVMGitHub.png
  3. When the download is complete, extract the zip file to C:\Program Files.

Configure Environment Variables

  1. Locate the folder where graalvm 11 is copied over (in the C:/Program Files from the step above)
  2. For example C:\Program Files\graalvm-ce-java11-windows-amd64-21.3.0\graalvm-ce-java11-21.3.0
  3. Open the System Properties dialog, select the Advanced tab and click Environment Variables.
    SystemProperties.png
  4. In the System Variables section, click New.
  5. Enter JAVA_HOME as the variable name.
    For the variable value enter the path to the GraalVM that you downloaded and extracted. For example C:\Program Files\graalvm-ce-java11-21.3.0.
    NewSysVar.png
  6. Click Ok.
  7. In the System Variables list, select the Path variable and click Edit.
  8. Enter your Java path, appended by \bin; at the beginning of the Variable value box. For example: C:\Program Files\graalvm-ce-java11-21.3.0\bin;
    EditEnvVar.png

Confirm Java Installation

  1. Open a Command Prompt.
  2. Type java -version
  3. Confirm that the correct version of Java has been installed.
    CMDJavaVersion.png

After the Java installation has been completed, proceed to the next step: Download Appvance AIQ

 

Last updated: October 7, 2026

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Windows Installation Guide for AIQ (GraalVM 11 Based)

Download Appvance AIQ

Contact the Appvance Customer Success Team for the location of the AIQ download that you should install.

  1. Download the AIQ .zip file. An example file name is something like: AIQ-5.x.x-345862.zip.
  2. Extract the zip file.
  3. The AIQ software is contained in the aiq_distribution folder.

Considerations

If you notice that extracting the Appvance IQ zip file is slow, the following may suggestions may improve the performance of that task:

After you have downloaded the AIQ software distribution, proceed to the next step: Installing and Configuring MySQL 8 Database (Windows)

 

Windows Installation Guide for AIQ (GraalVM 11 Based)

Install and Configure MySQL 8 for AIQ on Windows

Install and Configure MySQL 8 for AIQ on Windows

Use this guide when preparing a Windows-hosted MySQL 8 database for an AIQ environment. Confirm the supported database version, sizing, and security requirements before installing or changing an existing database.

Preparation

Validation workflow

  1. Install MySQL 8 using the approved Windows installer and configuration profile.
  2. Apply the required character set, time zone, networking, and service settings.
  3. Create the AIQ database/schema and account according to the installation plan.
  4. Test connectivity from the AIQ host before starting AIQ services.
  5. Run a login and small execution smoke test after AIQ is connected.

Maintenance note: Back up the database before upgrades, configuration changes, or cleanup operations.

Last updated: October 8, 2026

Windows Installation Guide for AIQ (GraalVM 11 Based)

Run AIQ on Windows as a Service

Run AIQ on Windows as a Service

Use this guide when AIQ must start automatically on a Windows host and run under a managed service account. Corrected the older title wording and replaced “Appvance IQ” phrasing with current AIQ terminology.

Preparation checklist

Validation workflow

  1. Start AIQ manually once and confirm login and a small smoke execution work.
  2. Install or configure the Windows service using the approved procedure.
  3. Start, stop, and restart the service from Windows Services or the service manager.
  4. Reboot the host if allowed and confirm AIQ starts automatically.
  5. Review logs for permission, path, port, or dependency errors.

Last updated: October 9, 2026

Windows Installation Guide for AIQ (GraalVM 11 Based)

Installing License and Certificate

AIQ requires a valid license file and a valid certificate for the server that hosts the Controller.

Install License

License files are distributed by the Appvance Customer Success Team or Appvance Support. Be sure that you have been provided a license file before you proceed.

  1. From your Appvance IQ URL, login and select Global Options > Admin Options > License (tab).
    AdminOptionsUploadLicense01.png
  2. Click Upload License.
  3. Browse to the license file provided by Appvance and click Open to load the license file.
    AdminOptionsUploadLicense02.png

 

Install Appvance Certificate

Every Appvance Controller requires a valid certificate. You may provide and install your own server certificate, or update and use the Appvance-provided certificate.

Provide your own certificate

  1. Copy your certificate to: <AIQ install path>\sahi\
  2. Install your certificate in Trusted Root Certification Authorities.
    See the Microsoft site for more information on Trusted Root Certification Authorities.

Update the Appvance-provided certificate

About the Appvance Certificate

The default Appvance certificate points to localhost and must be updated to point it to your specific IP or DNS. To do so, follow the steps in this topic.

Important

Generate an Appvance Certificate

This procedure assumes that your Appvance Control machine is already set up and running.

  1. On the Appvance Controller machine, login to AIQ.
  2. Navigate to Global Options > Admin Options > Certificate (tab).
    AdminOptionsCertificate.png
  3. Enter the DNS or IP of the AIQ controller. Do not enter a protocol or a port. For example: ec2-12-21-23-23.us-west-2.compute.amazonaws.com
  4. Click Update Certificate and Reboot.
    AdminOptionsCertificate02.png
  5. After a successful reboot, please use a new browser window and navigate to the AIQ Controller for the certificate to take effect. The browser may fail to load the IP address, the certificate still generate.
  6. Appvance generates the certificate, with a valid key store, inside the Appvance Controller machine's TestNode\certs directorySpaces and periods are replaced with '_' in the file name.
  7. Restart the Appvance services on Appvance Controller machine.
  8. Browse to <AIQ install directory>\sahi and double-click appvance.cer
  9. Click Install Certificate.
  10. Select Current User and click Next.
  11. Select Place all certificates in the following store and click Browse.
  12. Select Trusted Root Certification Authorities and click OK.
  13. Click Next.
  14. Click Finish.
  15. When the Certificate Import Wizard window appears, indicating the import was successful, click OK.
  16. Click OK.

Configuring Port 8443

Once installed, you need to configure Port 8443 for public access.

  1. In Windows Settings, open the Network and Internet. Select Advanced network settings.
    WindowsPort01.png
  2. Select the Windows Firewall option.
    WindowsPort02.png
  3. Select Advanced settings.
    WindowsPort03.png
  4. Select Inbound Rules.
    iWindows11.png
  5. In the Action tab, select New Rule.
    iWindows12.png
  6. In Rule Type, select Port.
    iWindows13.png
  7. In Protocol and Ports, select TCP and specify the local port as 8443.
    iWindows14.png
  8. In Action, select Allow the connection.
    iWindows15.png
  9. In Profile, select all the options.
    iWindows16.png
  10. Name the port.
    iWindows17.png
  11. Click Finish.

The AIQ controller firewall requires specific TCP ports open. Find the complete list in .Appvance IQ Production System Requirements.

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Windows Installation Guide for AIQ (GraalVM 11 Based)

Useful Utilities for AIQ Administration

Use utilities to support AIQ installation, troubleshooting, and administration. Utilities should help validate ports, certificates, disk space, network access, logs, browser dependencies, and service health without becoming undocumented production changes.

Examples of useful utility checks

Operational rules

  1. Use read-only checks first when diagnosing a production environment.
  2. Document any utility that changes configuration or service state.
  3. Do not paste secrets into command lines, logs, screenshots, or documentation.
  4. Prefer approved OS/package-manager tools over random downloaded utilities.
  5. Keep customer-specific scripts in a controlled repository with owners and review history.

Last updated: October 5, 2026

Windows Installation Guide for AIQ (GraalVM 11 Based)

Use getCssValue in Scenario Editor Scripts

Use getCssValue in Scenario Editor Scripts

Use getCssValue only when validating a CSS property is part of the test objective. For most functional tests, validate visible behavior or business output instead of implementation-level styles.

Maintenance notes

  1. Prefer stable locators for the element being inspected.
  2. Use conditional waits before reading style values.
  3. Document why the CSS property is business-relevant.

Last updated: September 18, 2026

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

A step-by-step guide for installing and configuring Appvance IQ on Mac OS X.

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

Download AIQ for macOS

  1. Download AIQ.
    If you do not have an Appvance IQ download link, please reach out to your Appvance contact, or email support@appvance.ai.


  1. Extract Appvance IQ to the desired install location.
    For example: /Users/<username>/AIQ

Next step: Install Java GraalVM11

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

Install Java GraalVM11

  1. Navigate to https://github.com/graalvm/graalvm-ce-builds/releases/tag/vm-21.3.0
  2. Locate MacOS (amd64) and click link/
    MacOS.png
  3. Open Terminal and change directory to Downloads.
    Syntax: cd $HOME/Downloads
  4. Unzip the archive. Note that <version> represents the graalvm version (ex: 21.3.0).
    Syntax: tar -xzf graalvm-ce-java11-darwin-amd64-<version>.tar.gz
    Example: tar -xzf graalvm-ce-java11-darwin-amd64-21.3.0.tar.gz
  5. Remove the quarantine attribute. Enter password when you are prompted.
    Syntax: sudo xattr -r -d com.apple.quarantine graalvm-ce-java11-<version>/
    Example: sudo xattr -r -d com.apple.quarantine graalvm-ce-java11-21.3.0/
  6. Move the directory package to JavaVirtualMachines.
    Syntax: sudo mv graalvm-ce-java11-<version>/ /Library/Java/JavaVirtualMachines
    Example: sudo mv graalvm-ce-java11-21.3.0/ /Library/Java/JavaVirtualMachines
  7. Verify the move was successful. You may now have more than one version listed.
    Syntax: /usr/libexec/java_home -V

Next step: Configure Java

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

Configure Java for AIQ

  1. Update your PATH environment variable to the GraalVM bin directory. (where <version> represents the graalvm version, ex: 21.3.0)
    Syntax: export PATH=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-<version>/Contents/Home/bin:$PATH
    Example: export PATH=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/bin:$PATH
  2. Update your JAVA_HOME environment variable to resolve to the GraalVM installation directory (where <version> represents the graalvm version, ex: 21.3.0)
    Syntax: export JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-<version>/Contents/Home/
    Example: export JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/
  3. Verify your install was successful.
    Syntax: java -version
    Sample Output:
    openjdk version "11.0.13" 2021-10-19
    OpenJDK Runtime Environment GraalVM CE 21.3.0 (build 11.0.13+7-jvmci-21.3-b05)
    OpenJDK 64-Bit Server VM GraalVM CE 21.3.0 (build 11.0.13+7-jvmci-21.3-b05, mixed mode, sharing)

 

Next step: MacOS Required Configurations for AIQ

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

MacOS Required Configurations for AIQ

The following steps are necessary to improve AIQ compatibility with macOS systems.

This configuration addresses a known issue that causes slowing in Java 8 applications with macOS Sierra or newer.

See StackOverflow for more information.

This configuration is required for macOS Sierra (10.12), High Sierra (10.13) Mojave (10.14), and earlier versions of Catalina (10.15.1 through 10.15.4).

  1. Type "hostname" in a terminal window to get your system's canonical name. This <system canonical name> should look similar to Joe-MacBook-Pro.local.
  2. Enter the hostname obtained in the first step into your /etc/hosts text file.
    1. Open the nano text editor to edit the /etc/hosts file by typing in a terminal: sudo nano /etc/hosts
    2. Assuming your hostname is "Joe-MacBook-Pro.local", then you should add two lines similar to this ones to the /etc/hosts file.
      127.0.0.1 Joe-MacBook-Pro.local
      ::1 Joe-MacBook-Pro.local
    3. Press Ctrl+O to write changes to the hosts file, and Ctrl-X to exit the nano text editor. Make sure to replace Joe-MacBook-Pro.local with your actual hostname returned by the command in the first step. Save your file, and retry executing your script in test designer.
      This change is NOT needed for recent Catalina OS releases (10.15.5+).

System Preferences

This configuration is necessary to be able to record and playback using Test Designer IDE using a Safari browser.

Safari Preferences

This configuration is necessary to be able to record and playback using Test Designer IDE using a Safari browser.

Safari opens with: A new private window. New window open with Empty PageNew tabs open with Empty Page

SafariGeneral.png

Select "When a new tab or window opens, make it active" in Tabs section

SafariTabs.png

Other optional settings in Safari Advanced tab:

Screen%20Shot%202017-03-08%20at%209.22.48%20PM.png

Apvance Certificate

Check if the Appvance Certificate is present (only needed if after the above steps you have Test Designer IDE recording problems)

The client installer for Test Designer scripts should automatically install Appvance 2020 SSL certificate in MacOS and in Mozilla Firefox (if present). But if you have problems recording on HTTPS sites, do validate if the certificate "Appvance 2020" is installed in the MacOS and/or Firefox.

Verifying the Appvance certificate is installed in MacOS

To check the MacOS certificates open the Keychain Access application and click over the tab. You should be able to find the "Appvance 2020" certificate with a blue dot (meaning it is trusted) as in this image:

Screen%20Shot%202019-11-28%20at%203.12.28%20PM.png

Catalina updates (May 2019) requires that the Appvance2020 certificate needs to be installed both in System and login keychains.

Installing the Appvance certificate in MacOS

If the certificate is not installed in Mozilla Firefox, you can download it from this link:https://aiq-client-installer.s3-us-west-2.amazonaws.com/appvance2020.cerThen click the "Import" button in the Firefox Certificate Manager and select the downloaded "appvance2020.cer" file.

Double-click the appvance2020.cer file and it will be added to the Keychain Access application. Locate the Appvance 2020 in the System Keychain and doble click over it to see its details. Expand the Trust option and select Always Trust in the first select box.Screen%20Shot%202019-11-28%20at%203.28.38%20PM.pngThe OS will ask for your password to trust this certificate and the screen should look like thisScreen%20Shot%202019-11-28%20at%203.30.49%20PM.png

Verifying the Appvance certificate is installed in Firefox

To check if the certificate is installed on Mozilla Firefox, open Firefox and open the Preferences, then type "Certificates" in the search input box. Click the View Certificates button to open the Certificates Manager:

Screen%20Shot%202019-11-28%20at%203.16.08%20PM.png

In the Certificate Manager, click the "Authorities" tab and scroll down until you find the Appvance 2020 certificate

Screen%20Shot%202019-11-28%20at%203.16.26%20PM.png

Installing the Appvance certificate in Firefox

If the certificate is not installed in Mozilla Firefox, you can download it from this link:https://aiq-client-installer.s3-us-west-2.amazonaws.com/appvance2020.cer

Then click the "Import" button in the Firefox Certificate Manager and select the downloaded "appvance2020.cer" file. Then click both trust checkboxes as in this image, and click Ok.

Screen%20Shot%202019-11-28%20at%203.32.46%20PM.png

 

Next step: MySQL Install & Setup

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

MySQL Install & Setup

Install MySQL Server

  1. Go to https://downloads.mysql.com/archives/community/
  2. Click Product Version and select 5.7.31
  3. Click Operating System and select Mac OS X
  4. Locate macOS 10.14 (x86, 64-bit), DMG Archive and click Download
  5. Open the downloaded package
  6. A warning may appear, with a legend similar to “can’t be opened because Apple cannot check it…” click OK
    MacOS02.png
  7. Select Apple Menu and click System Preferences
  8. Click Privacy & Security
  9. Click the General tab and select Open Anyway
    MacOS03.png
  10. Another warning may appear, click Open
    MacOS04.png
  11. When the Install MySQL installer appears, click Continue
    MacOS05.png
  12. Review the Software License Agreement, click Continue, then click Agree
    MacOS06.png
    MacOS052.png
  13. When the Installation Type window appears, click Customize
    MacOS07.png
  14. Ensure MySQL Server, Preference Pane and Launchd Support are selected, and click Install
    MacOS08.png
  15. Enter password when prompted
    MacOS09.png
  16. If the System Events.app warning appears, click OK
    MacOS10.png
  17. IMPORTANT When MySQL Installer provides the temporary password, note this password, it cannot be recovered!
    MacOS11.png
  18. When the Summary window appears, click Close

    If prompted you may move the installer to trash
    MacOS12.png
  19. Select Apple Menu and click System Preferences
  20. Click MySQL
  21. If MySQL is running, click Stop MySQL Server
  22. Click Start MySQL Server

Install MySQL Workbench

  1. Go to https://dev.mysql.com/downloads/workbench/ and download MySQL Workbench
  2. Open the installer
  3. When prompted, drag and drop MySQLWorkbench.app to Applications
    MacOS13.png

 

Next step: Install Appvance IQ Database Schema

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

Install Appvance IQ Database Schema

  1. Open MySQLWorkbench
  2. If warning appears, click OK
    MacOS14.png
  3. Select Apple Menu and click System Preferences
  4. Click Privacy & Security
  5. Click the General tab and select Open Anyway, and then Open
    MacOS15.png



    MacOS16.png
  6. If version compatibility issues occur, please try alternate download from https://downloads.mysql.com/archives/workbench/
  7. When MySQL Workbench appears, assuming a database connection does not already exist, click MySQL Connections + (add) button
    MacOS17.png
  8. Enter a name for the connection in the Connection Name box
    Enter the hostname, port and credentials (if needed) and click OK
    MacOS18.png
  9. Follow any prompts for updating the password
  10. Click the newly created connection, for example AIQ as illustrated below
    MacOS19.png
  11. Select File and click Open SQL Query Script...
  12. Browse to <AIQ>\TestNode\webapps\AppvanceServer\WEB-INF\classes\database
  13. Select MySQLInitial.sql and click Open
  14. Select Query and click Execute (All or Selection)
  15. Select File and click Open SQL Script...
  16. From the same location, select MySQLAppvance.sql and click Open
  17. Select Query and click Execute (All or Selection)

Troubleshooting

Error Code: 1419. You do not have the SUPER privilege and binary logging is enabled

If you get the above error while running the MySQLAppvance.sql script on AWS RDS, make sure that the RDS parameter group has the value 1 (ON) for the log_bin_trust_function_creators parameter. The RDS database MUST be rebooted for parameter changes to take effect.

Next step: Update MySQL Max Packet and Case Settings

Last updated: September 18, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Mac OS X Installation Guide for AIQ (GraalVM 11 Based)

Update MySQL Max Packet and Case Settings

  1. Open MySQLWorkbench
  2. Select Server and click Status and System Variables
    The Server Variables window appears
  3. Click the System Variables tab
  4. Enter max_allowed in the search box
  5. Update the max_allowed_packet value to 102400000 and press Enter
  6. Enter lower in the search box
  7. Update the lower_case_table_names value to 2 and press Enter


You may now close MySQLWorkbench

 

Next step: Anti-Virus Settings

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

Linux | Ubuntu Server Installation Guide for AIQ (GraalVM 11 Based)

Exclude files and folders from scheduled scans

The size of the Appvance IQ installation package is around 2 GB and is not expected to change until a new build is released. This folder should be excluded from the daily, weekly, or monthly scheduled scans as it will take up valuable scanning time. If the following folders are not excluded, you may see some unexpected behavior.

The list below are some of the top Anti-virus from which the files/folders of Appvance IQ should be excluded:

Installation Process

The instructions below assume that the Linux server is running Ubuntu. Ubuntu's package manager is apt-get.

If your Linux server is running Redhat / Fedora, replace the lines with corresponding yum commands.

  1. Initial steps.
    sudo chmod go+w /etc/hosts
sudo echo "127.0.0.1 $HOSTNAME" >> /etc/hosts
sudo chmod go-w /etc/hosts 
sudo apt-get update -y
sudo apt-get install wget -y 
sudo apt-get install zip -y
  2. Increase the open files linux limit in /etc/security/limits.conf.
    In a text editor just add the following lines at the end of the /etc/security/limits.conf file. The leading star ( * ) character is important.
    * soft nofile 500000
    * hard nofile 500000
  3. Getting GraalVM Community edition link.
    Navigate to GraalVM site https://www.graalvm.org/downloads/ and click the download button as below. On the release page you will be able to choose the correct platform for Java 11 depending on the technology supporting the server (AArch64 or x86-64). Copy the URL related to the download link.
  4. Installing GraalVM Open JDK Community edition.
    Using the download URL from the previous step, follow next steps to download, unpack and setup GraalVM Open JDK.

    cd /opt wget https://github.com/graalvm-ce-builds/releases/download/vm-22.1.0/graalvm-ce-java<version>-linux-amd64-<version>.tar.gz   // REPLACE LINK WITH PATH OBTAINED FROM PREVIOUS STEPtar -xzf graalvm-ce-java<version>-linux-amd64-<version>.tar.gz.  // REPLACE LINK WITH FILE NAME WITH THE ONE FROM PREVIOUS STEPexport PATH=/<path>/<to>/<graalvm>/bin:$PATHexport JAVA_HOME=/<path>/<to>/<graalvm>cd ~java -version
  5. When there are multiple versions of Java on the system.
    In case where system need to have more than one java version, need to select the graalvm as defaullt to AIQ can work properly.
    Adding a new alternative for "java" the third parameter assume that this is the only option for Java, in case there is another java version already installed, this third parameter would be 2, and so on.
    $ sudo update-alternatives --install /usr/bin/java java  /<path>/<to>/<graalvm>  1
$ sudo update-alternatives --config java
  6. Download and unzip AIQ
    cd /opt
sudo mkdir aiq
cd aiq
wget "https://<aiq_build_url)/<aiq_build_file>.zip".  (get the zip file from the latest release notes)
unzip <aiq_build_file>.zip
cd /opt
sudo chmod +x -R aiq
sudo chown -R ubuntu:ubuntu aiq

    For Azure Deployments create aiq sudo user: sudo chown -R aiq:aiq aiq
    AIQ will be installed after this setting. Just need to configure to point to the MySQL results database.

Installing MySQL 8 Community Server

The following step is not required if you will be using a separate MySQL server. Installing a separate MySQL server is recommended.

  1. Install local MySql 8 community server and run queries to set up the database
    If you will be saving to another MySQL server like Amazon RDS or Oracle DB server, this step is not necessary.
  2. Install MySQL 8 community server:
    1. sudo apt-get install mysql-server
    2. When prompted, enter (and note) password mysql -u root -p < /opt/aiq/aiq_distribution/TestNode/webapps/AppvanceServer/WEB-INF/classes/database/MySQLInitial.sql
    3. Password will be asked after the above query, provide valid passwordmysql -u root -p < /opt/aiq/aiq_distribution/TestNode/webapps/AppvanceServer/WEB-INF/classes/database/MySQLAppvance.sql
  3. Optional. Install Firefox and Xvfb (for web testing with Firefox browser only, so this step is not required if controller will not be running Firefox test designer tests.) sudo apt-get install firefox -ysudo apt-get install xvfb -y

Starting AIQ with /etc/rc.local

The following steps are related to setting the start of AIQ services on boot-up of the system.

There are two options for this: via /etc/rc.local file or by setting up a systemd service. This last option is recommended for test nodes running API test nodes.

This method is preferred versus systemd as rc.local startup is compatible with one click upgrade using Lab Management.

  1. Start aiq services as background process using rc.local, giving write permissions to rc.local.sudo chmod -R +x /etc/rc.localsudo nano /etc/rc.local
  2. Paste the following lines into /etc/rc.local:
    cd /opt/aiq/aiq_distribution/ && ./Appvance.sh

    Only in the case you want to use your controller to run Firefox test designer test cases then have your /etc/rc.local like the following:
    This requires you to install the xvfb X11 window server in ubuntu.
    Xvfb :99 -ac -screen 0 1280x1024x24 &export DISPLAY=:99
cd /opt/aiq/aiq_distribution/ && ./Appvance.sh

    For Azure Deployment on Ubuntu:

    #!/bin/sh -eexport JAVA_HOME=/<path>/<to>/<graalvm>export PATH=/path/to/<graalvm>/bin:$PATHXvfb :99 -ac -screen 0 1280x1024x24 &export DISPLAY=:99cd /opt/aiq/aiq_distribution/ && ./Appvance.shexit 0

     
  3. Save file changes:
    • Press Control + x
    • Press y + Enter
  4. Reboot.
  5. Navigate to http://servername:8080 or https://servername:8443.
  6. Login to AIQ using appvance/appvance.

Troubleshooting

If AIQ does not start:

Starting AIQ Using Systemd Service

Recommend this setting for test nodes that will be used for API load testing to make sure there are plenty of file handles available.

Current limitation for this method is that the one-click system upgrade using Lab Management does not support machines starting AIQ as a systemd service.

  1. Navigate to the system directory: cd /etc/systemd/system
  2. Create a text file in the system folder named appvance.service with following contents:

    [Unit]Description=Start Appvance IQ servicesAfter=syslog.target[Service]User=ubuntuType=simpleLimitNOFILE=1000000LimitNPROC=20000ExecStart=/bin/bash /opt/aiq_distribution/TestNode/startup.shWorkingDirectory=/opt/aiq_distribution/TestNodeTimeoutStartSec=0[Install]WantedBy=default.target

     
  3. Execute this command: systemctl daemon-reload
  4. Once installed, open port 8443 to public access.
    Ubuntu01.png
  5. If the port is not open, type:
    sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
    sudo service iptables restart
    sudo reboot
  6. After that enter the following browser URL : https://<Public IPv4 DNS>:8443/UI/index.html

Last updated: July 31, 2024

If you have any feedback on this topic, please contact us at documentation@appvance.ai

How to Install Appvance IQ results database in Amazon MySQL RDS

Setting parameter group

After creating a MySQL RDS database in Amazon AWS, you need to create a new parameter group by navigating to RDS > Parameter Groups > Create parameter group

After group is created, select Edit Parameters. The following values should be set:

ParameterValue
log_bin_trust_function_creators1
bulk_insert_buffer_size536870912
connect_timeout10
max_allowed_packet104857600
max_connections500
max_user_connections200
myisam_use_mmap1
read_buffer_size524288
validate_passwordOFF
wait_timeout1080 (AIQ-6619)

Assign the new parameter group to your database

After creating the new parameter group, assign it to the database and reboot it.

Then connect to the MySQL database using the admin credentials and execute MySQLInitial.sql and then MySQLAppvance.sql. No error should be visible in the execution. If an error happens, review the error message.

Error Code: 1419. You do not have the SUPER privilege and binary logging is enabled

If you get this error while running MySQLAppvance.sql on AWS RDS, make sure that the RDS parameter group has the value 1 (ON) for log_bin_trust_function_creators. The RDS database MUST be rebooted for parameter changes to take effect.

How to upgrade Appvance IQ Controller & TestNodes

Describes how to use Lab Management to upgrade an Appvance IQ Controller and its TestNodes.

If upgrading from 4.0.x to 4.1+, do not use Lab Management as described below. Instead please see Manual Upgrade Steps.

IMPORTANT: Mac OS X Servers / Linux Controllers

DO NOT use the Lab Management upgrade method to upgrade a Linux AIQ Controller which uses the /etc/systemd/system service. Lab Management only supports Linux upgrades where /etc/rc.local startup script is used. See Manual Upgrade Steps.

1. Create a Grid Configuration File

  1. Browse to Appvance IQ and login using an admin-level account
  2. Click Global Options and select Cloud Config
  3. Select the Grid Configuration tab

Controller

  1. Enter http://localhost:8080/TMServer/ws/Testnode in the Grid Machines box and press Enter
  2. Click Save, and save the Controller Grid Configuration file

TestNode

  1. Click Refresh to clear the form, select Grid Configuration again
  2. Enter http://<test-node-dns>:8080/TMServer/ws/Testnode in Grid Machines
  3. Press Enter. To add more machines, click Add Machine
  4. Click Save, and save the TestNode Grid Configuration file

2. Configure Lab Management

  1. Click Global Options, Admin Options (Lab Management tab)
  2. Click Add Cloud
  3. Enter a name in Cloud config name, select Grid in Type
  4. For each config file: click Browse, select the grid config file, click Save
  5. Select a Cloud to see all systems in the Machines list

3. Upgrade using Lab Management

  1. Click Global Options, Admin Options (Lab Management tab)
  2. Select a cloud location to upgrade in List of Clouds
  3. Tip: Upgrade Controller before TestNodes
  4. Confirm Machine Status displays Available
  5. If Machine Status displays Invalid Login, click the refresh icon
  6. Click Upgrade to begin
  7. Type UPGRADE (case-sensitive) in the confirmation box
  8. When complete, the version will reflect the new build

Prepping your Machine for First Recording | Test Designer

1. Install Pre-Requisites

Install Appvance IQ Certificate

IMPORTANT: Test Designer will not function without a valid certificate. If you installed an Appvance certificate prior to February 7th, 2022, you must still install the new Appvance certificate.

Download Certificate:

Windows Steps

  1. Double click the certificate file
  2. Select Local Machine
  3. Select Place all certificates in the following store
  4. Select Trusted Root Certification Authorities
  5. Click OK and Next

Mac OS Steps

  1. Double click the certificate file
  2. Right-click Appvance 2020 certificate, select Get Info
  3. Expand Trust, select Always Trust
  4. Close the Get Info window

Restart Browser

Quit and reopen your browser. This ensures the certificate is properly applied.

System Requirements

2. Install Test Designer

Mac

  1. Download TestDesigner-installer.dmg from https://AIQ_SERVER:8443/UI/TestDesigner-installer.dmg or via AIQ Login
  2. Log into AIQ, select Record a Designer Script
  3. When Designer Proxy Not Detected appears, click Download Designer Script Proxy
  4. Open TestDesigner-installer.dmg, double-click TestDesigner-installer
  5. If Cannot Open dialog appears, click Cancel, right-click and select Open
  6. If Cannot Verify dialog appears, click Open, enter password
  7. Click Next, accept agreement, click Next
  8. Accept install directory, click Next to begin installation
  9. Select Yes/No for user settings, perform system optimization if prompted
  10. Click Finish

Windows

  1. Download TestDesigner-installer.exe from https://AIQ_SERVER:8443/UI/TestDesigner-installer.exe or via AIQ Login
  2. Log into AIQ, select Record a Designer Script
  3. When Designer Proxy Not Detected appears, click Download Designer Script Proxy
  4. Run TestDesigner-installer.exe
  5. If Windows protected your PC, click More info then Run anyway
  6. Accept UAC prompt, select language, click OK
  7. Click Next, accept agreement, click Next
  8. Accept install directory, click Next to begin installation
  9. Select Yes/No for user settings, click Finish

3. Connect Repository

After installing Test Designer, connect to your AIQ repository by entering your AIQ server URL and credentials when prompted.

Troubleshooting

Install AIQ License and Certificate - Duplicate Review

This page appears to duplicate the AIQ license and certificate installation topic. Keep only one authoritative article when possible, and consolidate customer-neutral guidance into the primary license/certificate page.

Use this page only if

Consolidation checklist

  1. Compare this article with the primary license and certificate page.
  2. Move unique supported content into the authoritative page.
  3. Remove obsolete screenshots, duplicate steps, and old paths.
  4. Delete or redirect this page after content owners confirm it is redundant.

Last updated: October 7, 2026

Test Designer installed however buttons still Disabled

Problem

Test Designer is not working as expected

Reason(s)

  1. You are accessing internal private networks with settings which would be considered insecure for an external network

  2. With the many variations and versions of Java, multiple entries in your system’s PATH may exist and conflict with each other

Resolution

Chrome Security Update

This setting is for internal private network pages which may have insecure connections within your network. This does not impact external network security or sites.

  1. Enter in Chrome address bar

    chrome://flags/#block-insecure-private-network-requests

  2. Update setting to disabled

Verify your system is using a single Java version and path

This section contains:

Windows

  1. Click Start and enter System Env and select Edit system environment variables
    The System Properties window appears

  2. Click Environment Variables

  3. In the System variables list, select Path and click Edit

  4. Confirm only one entry exists for Java, for example:

    1. C:\Program Files\graalvm\graalvm-cd-java11-21.3.0\bin

  5. Remove any additional entries referring to Oracle or other java installs

  6. Click OK (3x)

  7. Go to C:\TestDesigner\NetworkProxy and run shutdown.cmd

  8. From the same location as above, run startds.cmd

Mac

  1. Stop the Test Designer proxy

    • Open Applications > Utilities > Terminal.app and enter the following

      cd $HOME/TestDesigner/NetworkProxy/
./shutdown.sh

  2. Verify your $JAVA_HOME path

    • Enter

      echo $JAVA_HOME

  3. If the $JAVA_HOME path output does not contain graalvm, then you need to determine if you have multiple Java versions on your system

    • Enter

      cd /Library/Java/JavaVirtualMachines/
ls

  4. If JavaVirtualMachines does not list more than one java version (more than one sub-folder), proceed to:

    1. Configure a Single instance of Java
      AND

    2. Remove duplicate Java entries in bash_profile

  5. If JavaVirtualMachines does list more than one java version (more than one sub-folder),

    1. AND you do not need to retain the non-graalvm java version(s), see "Configure a Single Instance of Java" to update $JAVA_HOME

    2. AND you do need to retain the non-graalvm java version(s), then

      1. Copy the path (including the folder name containing graalvm) and paste it in a temporary text file for use later. For example:

        /Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0

        AND

      2. Proceed to Modifying Test Designer’s Java Path

Modifying Test Designer’s Java Path

  1. Open $HOME\TestDesigner\NetworkProxy\startds.sh in nano or a text editor

    open $HOME/TestDesigner/NetworkProxy/startds.sh -a TextEdit

  2. Replace the $JAVA_HOME variable in startds.sh with the AIQ required Java version and path

    1. Locate the following lines in startds.sh (~line 35)

      if [ -f $JAVA_HOME/bin/java ]; then
 JAVA_HOMES=$JAVA_HOME/bin/java
else
 JAVA_HOMES=java
fi

    2. Replace $JAVA_HOMES (in this file only) with the graalvm java path (note, the path continues past the graalvm folder name). For example:

      if [ -f /Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/bin/java ]; then
 JAVA_HOMES=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/bin/java
else
 JAVA_HOMES=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/
fi

    3. Save and close the text editor

  3. Proceed to "Start the Test Designer Proxy"

Configure a Single instance of Java

  1. Update your PATH environment variable to the GraalVM bin directory (where <version> represents the graalvm version, ex: 21.3.0). For example:

    export PATH=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/bin:$PATH

  2. Update your JAVA_HOME environment variable to resolve to the GraalVM installation directory (where <version> represents the graalvm version, ex: 21.3.0). For example:

    export JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home/

  3. Verify your install was successful

    java -version


    Sample Output

    openjdk version "11.0.13" 2021-10-19
OpenJDK Runtime Environment GraalVM CE 21.3.0 (build 11.0.13+7-jvmci-21.3-b05)
OpenJDK 64-Bit Server VM GraalVM CE 21.3.0 (build 11.0.13+7-jvmci-21.3-b05, mixed mode, sharing)
Remove duplicate Java entries in bash_profile

  1. Verify old or duplicate entires do not exist in ~/.bash_profile (nano cheatsheet)

    cd $HOME
nano ~/.bash_profile

  2. When the nano editor appears, if you have more than one JAVA_HOME entry, remove any duplicates, retaining the graalvm entry (do not remove any non-java related entries). For example:

    export JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java11-21.3.0/Contents/Home
export PATH=$JAVA_HOME/bin:$PATH

  3. Save changes and exit nano (see nano cheatsheet for shortcuts)

Start the Test Designer proxy

  1. Return to the Terminal, and start the Test Designer proxy

    cd $HOME/TestDesigner/NetworkProxy/
./startds.sh

  2. When Test Designer starts, the graalvm java path should display in the logging that follows

You may now return to AIQ in the browser and refresh the Test Designer IDE page to begin recording Test Designer scripts.

Last updated: June 26, 2023

If you have any feedback on this topic, please contact us at documentation@appvance.ai