Installing the Galasa plug-in offline

The Galasa isolated.zip file is available from the https://resources.galasa.dev/ site and can be downloaded and extracted to a directory of your choice. The zip file contains three directories (eclipse, maven and javadoc), an isolated.tar file and a docs.jar file.

The eclipse directory contains the Galasa plug-in, and the maven directory contains dependencies that are required for building Galasa tests. The javadoc directory contains the Javadoc API documentation for the Galasa Managers.

The isolated.tar file is an optional Docker image that hosts all the artifacts. You might want to use the Docker image if you want to host Galasa on an internal server that can be accessed by other users. If you want to host Galasa on your local machine only, you do not need to use the Docker image.

The docs.jar file enables you to run the Galasa website locally on your machine or on an internal server. Instructions on how to do this are available in the README.txt that is provided in the Galasa zip file.

Getting started

Galasa installations can vary in complexity depending on the context in which it is used. Invariably though, all first-time installations begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. The Galasa plug-in is accompanied by Galasa SimBank - a demonstration application - which sits on top of a very small middleware layer called SimPlatform (you may see its name in some console messages, but you will otherwise not need to interact with SimPlatform).

This section describes the most common initial installation scenario - using Eclipse to install the Galasa plug-in - together with SimPlatform/SimBank - on your local machine and preparing it to run an initial set of provided tests against a simulated mainframe application.

Prerequisites

Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed.

Java

Galasa tests and Managers are written in Java - you will need to install a Java version 11 JDK or later to use it. Note: We do not currently support Java 17 or later.

Eclipse

If you do not already have an Eclipse installation, you can download a version of Eclipse appropriate for your machine. Choose a package that supports your required level of Java development - Eclipse IDE for Java Developers or Eclipse IDE for Java EE Developers. If you are unsure, then the Eclipse IDE for Java Developers should be fine, and you can always add plug-ins if and when you discover you need them.

You can check the current compatibility between Eclipse and Galasa versions in the table provided in the Getting started using Eclipse documentation.

Gradle

You will need to install Gradle version 6.8.2 which is used to build the Galasa software.

Docker (Required if using the Docker image)

If you want to deploy the Docker image that is provided in the zip file, you will need to have Docker installed.

(Optional) A 3270 terminal emulator

Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to explore Galasa Simbank, a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.

Getting started

Extract the contents of the zip file into a directory of your choice.

If you are using the zipped distribution hosted in Docker, ensure that you have the appropriate privileges to run Docker commands on the server on which you are hosting the Galasa artifacts and complete the following steps to load and run the Docker image:

Note: The example uses port 8080 but you can use a different port.

Within the directory that contains the Docker image (isolated.tar), run the following command:

docker load -i isolated.tar

The following confirmation message is received: Loaded image: icr.io/galasadev/galasa-distribution:latest.

Run the container by using the following command:

docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:latest

Go to http:\\hostname:8080 to view the running container.

You are now ready to install the Galasa plug-in.

Installing the Galasa plug-in

Launch Eclipse. If present, close any initial welcome screen.
Choose Help > Install New Software from the main menu.
Choose from the following options:
1. If you have the zip extracted locally, complete the following steps:
  1. Click Add and then Select Local
  2. Navigate to the directory into which the zip was extracted, select the Eclipse directory, and click OK
  3. Check that the Location field is populated with the filepath information, for example, file:///home/username/galasa-isolated-mvp/eclipse/ and press Enter.
2. If you are using the Docker hosting mechanism, populate the Location field with the URL to the running container, for example, http://hostname:8080/eclipse and press Enter.
Tick the Galasa box in the main panel, ensuring that Galasa and all of its child elements are ticked and press Next.
Follow the prompts to download and install the Galasa plug-in. You will be asked to accept the terms of the license agreement and restart Eclipse to complete the installation. You may also be asked to acknowledge and agree that you are installing unsigned content.
After Eclipse has restarted, you can verify that the plug-in is now available by observing the presence of a new Galasa option on the main menu between Run and Window. If you choose Run > Run Configurations from the main menu, you will also observe three new entries: Galasa - Gherkin, Galasa - Java and Galasa SimBank as available options in the left-hand panel of the pop-up window.

Configuring Eclipse for Galasa

Choose Galasa > Setup Galasa Workspace from the main Eclipse menu - this command creates some necessary configuration files. Your Eclipse console confirms its progress with some messages:

Setting up the Galasa workspace
Creating the ~/.galasa files
Created the ~/.galasa directory
Created an empty Bootstrap Properties file ~/.galasa/bootstrap.properties
Created an empty Overrides Properties file ~/.galasa/overrides.properties
Created an empty Credentials Properties file ~/.galasa/credentials.properties
Created an empty CPS Properties file ~/.galasa/cps.properties
Created an empty DSS Properties file ~/.galasa/dss.properties
The ~/.m2 directory already exists
Created the ~/.m2/.settings.xml example file
Setup complete

Locate your user home directory and confirm it contains a .galasa folder. On Windows, the user home directory resembles: C:\Users\<username>, on MacOS it will be /Users/<username> and on Linux /home/<username>. Note that any file or folder beginning with a . is a hidden folder, so you might need to change the settings on your operating system to show hidden files.

Edit a file called overrides.properties in your .galasa folder so that it contains:

zos.dse.tag.SIMBANK.imageid=SIMBANK
zos.dse.tag.SIMBANK.clusterid=SIMBANK

simbank.dse.instance.name=SIMBANK
simbank.instance.SIMBANK.zos.image=SIMBANK

zos.image.SIMBANK.ipv4.hostname=127.0.0.1
zos.image.SIMBANK.telnet.port=2023
zos.image.SIMBANK.webnet.port=2080
zos.image.SIMBANK.telnet.tls=false
zos.image.SIMBANK.credentials=SIMBANK

zosmf.image.SIMBANK.servers=SIMBANK
zosmf.server.SIMBANK.image=SIMBANK
zosmf.server.SIMBANK.port=2040
zosmf.server.SIMBANK.https=false

Edit a file called credentials.properties in your .galasa folder so that it contains:
```
secure.credentials.SIMBANK.username=IBMUSER
secure.credentials.SIMBANK.password=SYS1
```
Note: If you have previously installed Galasa, this file is already populated.

Your local Eclipse Galasa installation is now ready for some work. Start by exploring Galasa Simbank to help you to learn about the Galasa basics.

Edit this page on GitHub