Page History

Table of Contents

...

The intention of the tutorial these tutorials is to get provide a quick glimpse into the Airavat Airavata middleware by exercising its features through the hosted PHP version of Airavata Reference Gateway ; PGAwritten in PHP hence called PGA (PHP Reference Gateway for Airavata). The user can follow the carefully constructed user guide tutorials in order to receive experience general capabilities of the middleware.

...

Airavata Reference Gateway

Airavata PHP Reference gateway is the UI developed by the Airavata team for demonstration purposes and also for interested science communities to work with. This user manual Gateway is set of user interfaces to demonstrate the core functionalities provided by Airavata. This tutorial provides step-by-step information on for obtaining a complete science gateway experience for science and scholarly communities using Airavata as a middleware platform. In the user manual Here we would also discuss main features and services provided for gateway communities via Airavata.

User manual will facilitate;

At the completion of the quick-start-tutorials you would know:

• Gateway user registration and account verification steps

• How to use projects

• How to create and modify projects

• How to register users in PHP reference gateway.

• How to create, execute and monitor , etc... experimentsexperiments.

• How to share experiments and projects

• How to set up own cluster accounts for job submissions.

• How to seek assistance, submit issues , and provide user feedback and user request for new applications.

For more details on Airavata please visit Airavata site

Test/Demo Environment Details

1. PHP Reference Gateway link;
   https://testdrive.airavata.org
2. Download application input files from;
   https://cwiki.apache.org/confluence/display/AIRAVATA/XSEDE14+Gateway+Tutorial+Application+Input+Files+and+Parameters Generic sample application inputs 
   Sample application inputs for Gaussian and Gamess

Tutorial I - Gateway

...

User Account

Create Account

1. A new user has to create an account using ‘Create account’ link on top right-hand corner of the gateway top banner.
2. To create an account;
   1. Please enter User information and submit.
   2. Important;
      1. Username cannot have spaces.
      2. Username & password must be longer than 5 characters.Password is case sensitive.
      3. Password need to at least have (a) one lower case letter (b) one upper case letter (c) one number (d) One special character from !@#$%
      4. Enter all the mandatory fields indicated by a star; *.
   3. Account creation page
      1. Link:https://testdrive.airavata.org/createCreate User
   
   
3. Account PageImage Removed
   Image I - Create Account
   Account activation;
   1. The user will receive an email upon creating the account in the given provided email box address to confirm the account creation is real. User. The user needs to click use the link in the email and login to provide the gateway using the username and password.
   2. Initial user accounts will not have access to use the gateway; When the user account is first created it is not active; the user cannot submit jobs to resources. Gateway admin has to provide necessary access to each user activate the user account after validating the each user request for a gateway account.
   3. Gateway admin will notify access grant via email. 
   4. If the account confirmation fails, please contact you gateway admin through the Contact us.
   5. Gateway user will receive an email notifying change of privileges in the gateway when the account is active.
   6. If already logged in, the gateway user needs to log out and log-in againUser might need to logout from the gateway to be able to access job submitting permissions.

Login to Account

1. Once the account is created successfully; login log in to the gateway using the created account.
2. Gateway login screen link
   1. https://testdrive.airavata.org/login
3. OR
   1. use the 'Log In' link given on the 'Create New Account' page after account retain is successful.
   2. Login Page;

Image Removed

Image Added

Image I Image II - Login

Password Recovery

1. Gateway user can recover the forgotten password using '(Forgot Password? Click here)' link below in the login page.
2. User will be navigated to a page where the username needs to be provided.
3. An email will be sent wit ha link to enter The user needs to provide the username then will receive an URL to add the new password.

Tutorial II -

...

Using Projects

Create Project

1. 'Projects' within Airavata A Project is simply to group a set of grouping for experiments. Every user will have a 'Default Project' which is auto created exists when user the user logs into the gateway for the first time.
2. To create Projects navigate to ‘Project --> Create’ from the main menu. Enter Project Name (Mandatory) & Project Description (Optional) and Savesave.
3. Project creation Screenscreen
   Image RemovedImage Added
   Image II - Create Project
4. Prior to submission, fields can be cleared using Clear button.
5. User will be navigated Upon successful creation, the user is directed to Project Summary page upon successful creation of the project.

...

Browse Projects

1. Screen navigation Navigation 'Project --> Browse' from the main menu.
2. Search keys are;
   1. Project Name
   2. Project Description
3. Search Browse Project Pagepage;
   Image RemovedImage Added
   Image III - Search Browse Project
4. After selecting the search by key, user has to give  a value to search using the selected key. Click on Search.
5. All the Projects as per entered key value pair will be listed.
6. User The user can search for all projects by using (*) as a wild character. The * can be used when searching either optionsoption; Project name or description.
7. When projects are listed by clicking ‘View’ at the end of the row user can navigate to ‘Project Summary’ page. 

Image Removed

Image IV - Browse Projects

...

1. In 'Project Summary' all experiments created under the project will be listed

...

1. along with the list of shared users.
   Image Added

1. 
   Image

...

1. IV - Project Summary

...

1. The user can click on the experiment

...

1. ‘Name’ and navigate to ‘Experiment Summary’ page.

Image Removed

Image VI - Experiment Summary

...

Share Projects

1. Projects are also used to share with other gateway users. e.g.: Sharing a project with another user will give him access to all his experiments in the project.

2. When sharing projects, the project owner can share with 'write' or 'read' access.

3. Once a project is shared with other users, they will be listed on the project summary page. Refer Image Image IV - Project Summary

4. Sharing with 'read' access will enable the users to view the project and experiment in the project. Only the owner can modify the project details and sharing.

5. Sharing with 'write' access will enable the users to view the project and experiment in the project, modify the project and create new experiments using this project. Still, only the owner can modify the project sharing.

6. The project owner can remove, modify sharing of existing users and share with new users at any given time.

Tutorial III - Configure Individual Account on Clusters

1. Gateway user can use their own compute resource (cluster) allocation (if exists. if not can use the community allocation) within the gateway to launch jobs.
2. Prior to using the allocation users need to set up the allocation account details in the gateway.

Add Allocation

1. Navigate to User Settings (This is under gateway username in the menu on the righthand side.
   Image Added
   Image V - User Settings Navigation
2. User Settings screen
   Image Added
   Image VI - User Settings 
3. Select 'Compute Resources' from above to add allocation details.
4. Click 'Add a Compute Resource Account'
5. Select the resource from the drop-down list.
6. Provide the required information. NOTE: You may not have allocation project, QOS or Reservation. The minimum requirement is the login username and the scratch location and SSH key.
7. When assigning SSH key by default the default SSH key will be assigned. If the user prefers, can generate a new key and assign here.

Credential Store

1. For individual users to generate new SSH key navigate to User Settings → Credential Store
2. In Credential store you will have the default key displayed and it can be copied to add to your account's 'authorized_keys' file.
3. To generate a new key provide a description and add.
   Image Added
   Image VII - User Settings → Credential Store
4. User can delete keys and also tag any key as the 'default' SSH key.

Add SSH Key to Authorized Keys

1. SSH keys are generated for secure communication between airavata middleware and compute resource.
2. Once SSH key is generated, it needs to be added to the authorized keys file for the user in the respective compute resource/cluster.
3. To add the SSH key login to your account in the cluster.
4. Navigate to .SSH directory and open authorized_keys.
5. Add the SSH key assigned in user settings and save.
6. If you have don't have .ssh directory or the authorized_keys file, create them.

Tutorial IV - Create & Launch Experiment

Create Experiment

1. To create an experiment click on ‘Create Experiment’ from the main menu. Navigation  Navigation to experiment creation page Main Menu --> Experiment --> Create Experiment
2. Create Experiment Page - Experiment Information
   Image RemovedImage Added
   Image VII VIII - Create Experiment
   
   
3. Initially user needs to First enter/select given fields in order to continue.;
   1. Experiment Name (Mandatory)
   2. Experiment Description (Optional)
   3. Project (Select from the available LOV. Latest will be on top; auto selected)
   4. Application (Select from the available LOV)
   and click on ‘Continue’ button. At this point, the user can clear any entered fields by clicking ‘Reset Values’ before continuing.
4. Then continue entering Application configuration information.
   1. Experiment application input (Mandatory) - Application input can be in the form of entering data manually or uploading a single or multiple required input files.
      NOTE: Uploading file validity is not checked by the gateway. User has the responsibility of uploading correct files.
   2. Compute Resource (select from the available LOV. If the application is existing in a single resource, it will be the default value)
   3. Queue (a default value will be taken if not changed by the user)
   4. Node Count (If not entered default value will be taken as the input)
   5. Total Core Count (If not entered default value will be taken as the input)
   6. Wall Time Limit (If not entered default value will be taken as the input)
   7. Total Physical Memory (If not entered default value 0 will be taken as the input)
   NOTE:
   1. For values d, e and f if user does not enter,  default value will be taken as the input. Notifications: Add email address if required to receive job starting and completing notifications from compute resource itself.
      NOTE: For some compute resources, this above default value values will not be correct. User needs to change the node count in such cases.
   2. For d and e user has to enter a value greater than or equivalent to 1.
   3. For f user has to enter a value greater than or equivalent to 0.
5. Create Experiment - Application Configuration Part
   Image AddedImage Removed
   Image VIII IX - Create Experiment Contd..
   
   
6. While entering application configurations user can start over from the beginning using ‘Start Over’ button.
7. Once saved or saved and launched user will be directed to ‘Experiment Summary’ page; can refresh the page and from summary page can monitor experiment status changes.
8. Experiment Summary Page
   Image RemovedImage Added
   Image IX X - Experiment Summary

Launch Experiment

To launch an experiment can use the same
1. The experiment can be launched using 'Create Experiment' screen.
Apart from saving the experiment user can
2. Click  'Save & Launch
at the same time using button ‘Save and Launch’.User can also create and save the experiment to launch later. To launch later user has to navigate to
3. ' button to directly launch the experiment.
4. If the experiment was just CREATED for a later launch, the user can launch from 'Experiment Summary' Page
.

5. If the experiment is not supposed to launch e.g.: a COMPLETED, LAUNCHED experiment, then the launch button will be disabled.

...

1. . For experiments that are 'launchable' 'Launch' button will be enabled in summary page.
   NOTE: Experiments only in CREATED state can be launched.

Tutorial V - Browse Experiments

1. User can search for experiment created by him/her through
   1. Experiments → Browse
      OR
   2. Browse Projects → View Project → View Experiment (by clicking on the status of the experiment) - Please refer Search Projects in "Tutorial II" above.

2. In

Search

3. Browe Experiments search keys are;

1. Experiment Name

2. Experiment Description

3. Application

4. …

4. Browse Experiments Page

Image Removed

...

1. Creation Time - User can provide 'From Date' and 'To Date'

   Image Added
   

   Image XI - Browse Experiments

1. All the experiments of the user will be listed; latest on top.

User  can also select the search by key, user has to give  a value to search for using the key. Partial

2. The user can also search using provided keys with partial values, complete values, (*)

wild card can be used to search.

3. Click on Search once the search key is selected and value is entered. User can also search for experiments by giving the status.

All the experiments as per entered Key value pair will be listed

4. wildcard. Above search can be narrowed by combining with experiment status as well.

5. By clicking on the 'Status' user will be navigated to ‘Experiment Summary’ screen of each experiment.

In experiment

6. Experiment summary

users

7. can be used to;

   1. Launch experiment - Explained in above Tutorial III

   2. Cancel experiment

   3. Clone experiment

   4. Edit experiment

8. User can edit an experiment by navigating to 'Edit Experiment' page. Edit button next to each experiment name will navigate user to 'Edit Experiment' page of each experiment.

...

1. 1. View experiment data files (Inputs, outputs, archived files)

Tutorial VI - Modify, Cancel, Clone &

...

Share Experiments

Modify Experiment

1. Modify experiment by clicking on the edit icon (pencil) next to experiment name (In Browse Experiment, Project Summary) OR by clicking on ‘Edit’ button in Experiment Summary Page.
User can
2. User can modify all available fields except experiment status, project, application & experiment ID of experiments only in CREATED state.  

3. User can update experiments with statuses;

1. CREATED

4. Edit Experiment Page

Image Removed

Image Removed

Image Added

Image Added

Image XII Image XI - Edit Experiment

Cancel Experiment 

1. Experiments can be canceled by navigating to experiment’s To cancel use 'Cancel' button in 'Experiment Summary’ screen.
2. Experiment statuses which allow cancellations;
   1. LAUNCHED
   2. EXECUTING
   3. SCHEDULED
   with statuses LAUNCHED and EXECUTING can only be canceled.
3. When canceled, Click on ‘Cancel’ button and immediately the Experiment status will change to CANCELING.
4. If the job is not already processing processed in the remote resource (already COMPLETED in the resource) the job will proceed to COMPLETE and upon completing the have COMPLETE state and experiment status will change to CANCELLED. Since the user requested a cancellation generated output will not be provided back to the gateway.
5. If the job was successfully CANCELLED upon changing the job state to CANCELLED experiment status will also change to CANCELED.
6. CANCELED Once canceled, experiments are only available for cloning in the PGAonly available for cloning, cannot resume.

Clone Experiment

1. Experiments can be cloned irrespective of the experiment status by clicking ‘Clone’ in ‘Experiment Summary’ page.
2. When clicks ‘Clone’ from experiment summary user will be navigated to ‘Edit Experiment’ page of the new experiment. The new experiment will have exact same information as the earlier existing experiment.   
3. The new experiment will have a new experiment ID and the status will always be CREATED.
   New experiment name = Clone of + Old experiment name
4. UserThe user can change existing information (except the Application) in ‘Edit Experiment’ page and save or save & launch.

...

Share Experiment

1. A user can share his or her work with other gateway users at experiment level and at a project level. Project level sharing details 

Tutorial VII - User Assistance

Report Issue

1. Gateway user can report issues faced within the gateway through this page.

2. Page navigation: Help → Report Issue

3. Raise a Bug Page

Image Removed

Image XII - Raise a Bug

Request Feature

1. Gateway allows users to provide feedback as well as request for new applications via Request Feature Page.

2. Page Navigation; Help → Request Feature

3. Got Feedback? Page

Image Removed

...

'Contact Us' in home page provides communication with the gateway admin via email. Gateway users can use this for all gateway related communications such as

1. Report an issue
2. Request for a feature
3. Feature clarification