.. role:: raw-html(raw)
:format: html
.. |rocket-icon| replace:: :raw-html:``
.. _lexis-portal:
.. _quick_start:
###########
Quick Start
###########
We would like to rocket fast |rocket-icon| guide you through the initial steps of using the LEXIS platform via the web portal. Our goal is to help you run your first computational workflow and upload your first dataset!
.. image:: FirstStepsImages/fsteps_show_guide.png
:target: ../../_images/fsteps_show_guide.png
:width: 240
:align: center
:alt: Open guided tour in web application
You can also try our in-build guided tour, which can be optionaly opened in the right top submenu. For more details read the paragraphs below.
Before using the portal, logging in to the user account is required. **Login button can be found in right-top corner** on `portal.lexis.tech `_. You can login in using `MyAccessID `_ *(eduGAIN, eIDAS)* or `B2ACCESS `_ *(eduGAIN, ORCID and Social Identities)*.
.. image:: FirstStepsImages/fsteps_sign_in_options.png
:target: ../../_images/fsteps_sign_in_options.png
:width: 240
:align: center
:alt: Login in application
After logging in, we need to **create a** :ref:`LEXIS Project`. To do this, click the green button in the middle of the screen, or go to *Projects* in the navigation menu on the left and then click the green button on the right.
.. figure:: img/access_or_create_project.png
:width: 240
:align: center
:alt: Access or Create LEXIS project
Next, it is necessary to add in the details about the new project.
.. figure:: img/create_project_form.png
:width: 360
:align: center
:alt: Access or Create LEXIS project (Create Form)
**Execution of workflows and storing files requires a** :ref:`LEXIS Computation Resource`. To assign **one with computation time** and **one with data storage allocation**, click on *Resources* next to the created project on the *Projects* page.
.. figure:: img/Resources_button_in_project.png
:width: 360
:align: center
:alt: Resources button in project
Then click on *Request Resource Access* and fill out the form.
.. figure:: img/Request_Resource_Access_button.png
:width: 768
:align: center
:alt: Request Resource Access button
Wait until the PI of the resource accepts your request. If you are the PI, an email will be sent to you with a one-time link to accept the request. To assign a storage resource, fill in the resource name as *"iRODS LEXIS V2"*, choose the provider *"IT4Innovations"*, and fill in the email field with *"support@lexis-project.eu"*.
.. figure:: img/resource_form2.png
:width: 240
:align: center
:alt: Request LEXIS Computation Resource
.. TODO: upload dataset, create custom script workflow, execute workflow
Before executing some computation on LEXIS Platform, you would like probably to upload some input data. To do that, navigate to *Data Sets* and *Uploads* section via navigation menu on the left side. You will find yourself on page with all accessible uploaded data sets list.
.. figure:: img/upload_dataset_button_wayto.png
:width: 768
:align: center
:alt: Upload LEXIS Dataset (button)
By clicking on green button *Upload Dataset*, following form will appear.
.. figure:: img/upload_dataset_form.png
:width: 768
:align: center
:alt: Upload LEXIS Dataset (form)
For uploading data an existing assigned :ref:`LEXIS Computation Resource` to a :ref:`LEXIS Project`. Access defines visibility scope of dataset to one of user (dataset owner), project (all members in the project), public. Every dataset can have metadata.
.. figure:: img/upload_dataset_metadata.png
:width: 768
:align: center
:alt: Upload LEXIS Dataset - metadata (form)
.. figure:: img/upload_dataset_summarization.png
:width: 768
:align: center
:alt: Upload LEXIS Dataset - Summarization (form)
Afterwards, dataset will appear in a dataset list. Now, the dataset can be used as input dataset for :ref:`LEXIS Workflow`.
.. figure:: img/uploaded_dataset_in_list.png
:width: 768
:align: center
:alt: Uploaded LEXIS Dataset in list
To create workflow, navigate to *Applications* and *Custom HPC Jobs*. Click on green button *Create Jobscript*.
.. figure:: img/create_jobscript_button_wayto.png
:width: 768
:align: center
:alt: Create jobscript button
Use following code as :ref:`example job script ` and continue.
.. _example-custom-job-script:
.. code-block:: bash
# Example Job Script for LEXIS Workflow
source /cvmfs/software.eessi.io/versions/2023.06/init/bash
ls ./input # in this directory should appear staged input dataset
cat ./input/vinice-geojson.json # reads content of uploaded file to dataset
echo "I am running!!"
.. figure:: img/custom_job_script.png
:width: 768
:align: center
:alt: Example Job Script with vinice-geojson
.. figure:: img/custom_job_script_wf_summary.png
:width: 768
:align: center
:alt: Example Job Script with vinice-geojson - summary
Now the job script for workflow is prepared and workflow can be created by clicking *Create Workflow* next to the prepared job script in *Custom HPC Jobs* page.
.. figure:: img/create_workflow_custom_job_script.png
:width: 768
:align: center
:alt: Example Worfklow from Job Script with vinice-geojson
.. figure:: img/create_workflow_jobscript_1.png
:width: 768
:align: center
:alt: Create Worfklow step 1
In second step, one of assigned resources to the project is selected together with execution cluster and partition.
.. figure:: img/create_workflow_jobscript_2.png
:width: 768
:align: center
:alt: Create Worfklow step 2
The data input is enabled and default dataset is selected. The dataset will be staged to */input* directory relative to HPC job execution contex
.. figure:: img/create_workflow_jobscript_3.png
:width: 768
:align: center
:alt: Create Worfklow step 3
.. figure:: img/create_workflow_jobscript_4_summary.png
:width: 768
:align: center
:alt: Create Worfklow step 4
After creation of workflow, it will finally appear after a few seconds in *Custom HPC Script Worfklows* section in *Custom HPC Jobs* page.
.. figure:: img/created_jobscript_worfklow.png
:width: 768
:align: center
:alt: Created Worfklow in list
Now, it is ready to create first execution. Click on green *Execute* button and fill the form.
.. figure:: img/execution_form.png
:width: 768
:align: center
:alt: Workflow execution form
In the execution detail, there is visualisation. Particular steps produce logs, which are accessible by moving the cursor over the step and clicking on the *Logs* button.
.. figure:: img/execution_logs_failed.png
:width: 768
:align: center
:alt: How to find execution logs on failure
Logs from HPC job can usually be found in *...heappe_job_waiting* task's log.
.. figure:: img/workflow_job_log.png
:width: 768
:align: center
:alt: HPC job logs
.. _final-job-log:
Job log - partial GeoJSON content and "I am running" message
.. code-block:: pypylog
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - [
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - 16.64590904709604,
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - 48.810181792975015
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - ],
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - [
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - 16.64727894500959,
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - 48.81075254030276
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - ]
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - ],
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - "type": "LineString"
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - }
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - }
[2024-07-18T11:58:00.642+0000] {logging_mixin.py:188} INFO - ],
[2024-07-18T11:58:00.643+0000] {logging_mixin.py:188} INFO - "bbox": null
[2024-07-18T11:58:00.643+0000] {logging_mixin.py:188} INFO - }
[2024-07-18T11:58:00.643+0000] {logging_mixin.py:188} INFO - I am running!!
[2024-07-18T11:58:00.650+0000] {base.py:293} INFO - Success criteria met. Exiting.
[2024-07-18T11:58:00.672+0000] {taskinstance.py:1138} INFO - Marking task as SUCCESS.
That's it! Thank you for your patience, and we hope you enjoy the LEXIS platform.