Description

This article provides step-by-step instructions for a new GenRocket Runtime setup on an individual's local machine or a shared, central machine running the Linux or Mac operating system. When running on a central machine accessed by many users, remember to set up Runtime in a shared, accessible location. 


Important: These steps should be followed only after you have completed the prerequisite steps listed in this article: GenRocket Runtime Overview.


Command Line Video Example

This video (5:54) presents a complete step-by-step process for installing the GenRocket runtime on a computer via the command line. Thus, it best targets individuals comfortable navigating to and operating within a command-line terminal.


Runtime Setup Step-By-Step Instructions


Note: The images below show how to perform these steps for Mac OSX. Some steps might vary if you are using the Linux operating system.


Step 1 - Download GenRocket Runtime

The zipped file can be downloaded directly from the GenRocket web platform or using a CURL or Wget command. The version number may differ from the one in the images and commands below. You can view the most recent version number in the GenRocket web platform (as shown in Option 1 below). 


Method 1 - Download from the GenRocket Web Platform

  1. Log into the GenRocket Web Platform
  2. Select the Options menu.
  3. Select Download Runtime #.#.##.



Method 2 - CURL or Wget Command

You can download the runtime directly and place it in any location using the CURL command. Your machine must support CURL for this option. You'll need your GenRocket URL, Organization ID, and Version Number. 


You can also use a wget command if it is supported by your operating system. Replace 'curl' with 'wget' in the curl command. The rest of the command is the same. 


For more information, please see this article: Using CURL Commands to Download Runtime, Jars, Docker Image, and Server/User Profile.


Step 2 - Unzip (Extract) the Downloaded File

This can be done from a terminal window or through the user interface.


Method 1 - Command Line

Open a terminal window and ensure its path is set where the zipped file is located. Then enter this command (#'s represent the version number):

unzip genrocket-#.#.##.zip


Method 2 - User Interface

  • Open Finder and navigate to the directory where the file was downloaded (e.g., Downloads folder).
  • Right-click on the file and select Open to extract it automatically.




  • When extracted, the folder name will appear like genrocket-#.#.# (the #'s are digits).



Step 3 - Rename the File to 'genrocket'

This can be done from a terminal window or through the user interface


Method 1 - Command Line 

mv genrocket-#.#.## genrocket


Method 2 - User Interface

  • Right-click on the folder name and choose Rename.
  • Remove "-#.#.#" from the folder name.


  • It will appear as shown below once renamed:



Step 4 - Move to Home Directory

Stop! You don't need this step if you download the genrocket runtime file to the home directory using a CURL or Wget command and unzipped it in that location.


Method 1 - Command Line

You can use the following command to move the genrocket folder to your home directory.

cp <file path> <destination path>


Example:

cp ~/downloads/GRXXXXXXXProfile.grp ~/.genrocket


Method 2 - User Interface

Move the genrocket folder to your home directory (typically /home/users/username). Complete these steps: 

  • Right-click on the genrocket folder and select Copy "genrocket".



  • Navigate to your home directory using this shortcut key combination: CMD+SHIFT+H.
  • Right-click and select Paste Item to paste the folder into your home directory.



Step 5 - Modify Environment Variables in the Shell Startup File

To complete the runtime setup, you'll need to edit your shell's startup file. This is where the permanent environment variables are stored. The required file is stored in your home directory, and the name differs per operating system.  


What Shell File Name Should I Use? 

Below are the two most common. The file name will vary per shell.
 

Shell NameCommon Names
Bash shell (.bash)Typically one of the following: .bashrc, .profile, or .bash_profile
Zsh shell (.zsh).zhrc (example - .zsg.zshrc)

  

Bash Example


 Zsh Example



How to Access the Shell File

Open a terminal window and enter the following command. Replace <shell file name> with the name of the shell file (e.g., .zsg.zshrc, .bashrc, .bash_profile). 

nano <shell file name>


Examples: 

nano .bash_profile
nano .zsg.zshrc
HTM


Environment Variables to Add to Shell File

Each should be added on its own line in the shell file. 

VariableValue
GENROCKET_HOME Environment VariableThis is a user variable on a user's local computer but will be a system variable when Runtime is installed in a shared location. The variable should point to your home directory. 

Mac OS
Value: export GEN_ROCKET_HOME=~/genrocket

Linux OS
Value: export GEN_ROCKET_HOME=/home/username/genrocket 

PATH Environment VariableThis is a user variable on a user's local computer but will be a system variable when Runtime is installed in a shared location. 

Linux and Mac OS
Value: export PATH=$PATH:$GEN_ROCKET_HOME/bin

JAVA_HOME 
System Environment Variable		This variable is already set in most instances if JAVA is installed. However, an invalid path can be present when using more than one version of JAVA, resulting in an error during setup. Therefore, it is recommended that you verify the path.

Generic Example
Value: export JAVA_HOME=<java path>

JAVA_OPTS System Environment Variable

Version 1.8 - JAVA_OPTS is Not Required

Version 1.11 - Required JAVA_OPTS Variable Value

JAVA_OPTS=-Xms512m -Xmx2048m --add-opens java.base/jdk.internal.loader=ALL-UNNAMED --add-opens jdk.zipfs/jdk.nio.zipfs=ALL-UNNAMED


Version 1.17 - Required JAVA_OPTS Variable Value

export JAVA_OPTS - JAVA_OPTS=--add-opens=java.base/java.lang=ALL-UNNAMED


Note: -Xms512m -Xmx2048m is optional and can be helpful for generating a large amount of data. When used, it explicitly says to reserve a minimum of 512 MB memory and a maximum of 2048 MB.


Optional JAVA OPTS Variable Value for Performance
Some Generators use memory to maintain the uniqueness of the random data being generated. To improve performance or resolve memory issues during test data generation, add the following to the  JAVA_OPTS environment variable.


-Xms512m -Xmx2048m -XX:PermSize=512m -XX:MaxPermSize=2048m


Text
HTM


User Steps (.bash example)

Enter each item above on a separate line. You can copy and paste the information into your shell file.  
  • The first line should point to your path, which may vary per computer. 
  • For Mac OS, the default is the home directory. The first two lines will appear as shown below: 
  • The other line for JAVA_OPTS will be the same as shown above.

    export GEN_ROCKET_HOME=~/genrocket 
export PATH=$PATH:$GEN_ROCKET_HOME/bin



  • Press Control+X to exit.
  • Enter Y to save the change.



  • Press the Enter Key to write to the displayed file.


Step 6 - Run the 'genrocket command in the Terminal Window

By putting $GEN_ROCKET_HOME/bin on the path, you can execute the shell script to complete the installation from any location.  


Open a new terminal window and run the genrocket command. This will download the other dependent jars. 

genrocket



If you do not receive any errors, you are all set. The above command should create a hidden .genrocket folder in the user's home directory or the shared directory (multiple users). You may need to unhide this folder to see it. 

Did you receive an Error Message? Click here to see troubleshooting recommendations for typical GenRocket Runtime installation errors.


If the 'genrocket' command does not download the additional jar files automatically, you can download them manually from the GenRocket web platform or by using CURL commands. The downloaded jars should be placed in /home/users/username/genrocket/lib. 



Step 7 - Download Helper Libraries

Next, run the genrocket -lib command to download the GenRocket Helper Libraries, which the Engine API, GMUS, and other Genrocket components require.

genrocket -lib



Note: If this command does not work on your machine, you can download these files from the Options menu in the GenRocket web platform. They need to be placed in the .genrocket folder in your home directory (usually /home/users/username/).


Step 8 - (Each User) Add Values for Organization Resources

Each user must perform this step in order to download their profile (required by Runtime). Three default resources are available (shown below). If any other resources appear here, your organization has added them. Please get in touch with your Org Admin for any resources outside of the default three. 


Complete these steps to modify resource values: 

  • Go to the Project Dashboard. 
  • Click the Pencil to fill in each resource value.



  • The value for the resource.home.directory will be the user's home directory.

    • /home/users/username

    • e.g. - /home/users/johndoe

  • You can find the home directory by running the following command in the terminal window:

    echo $HOME


  • The rest of the resource values can be any arbitrary location.


Step 9 - (Each User) Download Your Profile

Your user profile (GRXXXXXXXProfile.grp) is required to use the GenRocket Runtime. This file must be downloaded and placed into the .genrocket folder.  For a shared machine, each User Profile will need to be placed in the .genrocket folder in the shared location where Runtime is installed. To learn more about this file, click here.


Method 1 - User Interface

  • Log into the GenRocket web platform to view the Project Dashboard.

  • In the Resources pane, expand the Download menu and select Download My Profile.

  • The file will be downloaded to your Downloads folder.



Method 2 - CURL Commands

Two CURL commands are required for this method. The first command obtains the access token, which the second command requires. Organization ID and version information can be obtained from the GenRocket web platform. To see these commands and learn more, click here.


Step 10 - (Each User) Move Your Profile to the .genrocket Folder

This is the folder created in Step 6 of this article. You can move the profile by entering a command in the terminal window or using Finder. 


Method 1 - Command Line

Use the following command to move the file to the .genrocket folder. Ensure the path points to the file's current location (e.g., downloads folder). 

cp <file path> <destination path>


Example: 

cp ~/downloads/GRXXXXXXProfile.grp ~/.genrocket


Method 2 - User Interface

  • Open Finder and navigate to your Downloads folder.
  • Right-click on your profile file and click Copy "GRXXXXXXXProfile.grp".


  • Navigate to and open the .genrocket folder in Finder (this is usually \Users\User Name). 
  • This can be easily found on a Mac with this key combination CMD+SHIFT+H.
  • Open the .genrocket folder, right-click in an empty area, and select Paste Item.



  • You can now run GenRocket Scenarios on your local machine using GenRocket Runtime.



Validate Installation

After following the steps in this article, please take a few moments to verify that the installation has been completed. You'll be able to do so by following these steps.  

  • Log into the GenRocket web platform. 
  • Create a Project with 1 Domain and 1 Scenario.
    • A sample project has been created with a User Domain and User Scenario.
    • The DelimitedFileReceiver has been assigned and will generate one record as a delimited file.


  • Download the Scenario to your local computer.
  • Open a terminal window and make sure the source is set to your shell file. Example command: 
    source ~/.bash_profile
    source ~/.zsg.zshrc


  • Run the Scenario by entering the following command in a terminal window: 
    genrocket -r <ScenarioName>.grs

    Example: 

    genrocket -r UserScenario.grs


If you do not receive any errors and the file is created, then GenRocket Runtime has been set up correctly. File data is shown below: