SequenceTubeMap-Sapelo2: Difference between revisions

From Research Computing Center Wiki
Jump to navigation Jump to search
(Initial creation of page)
 
m (Made a note that SSH tunneling may cause the terminal to appear frozen.)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Sapelo2]][[Category:Software]][[Category:Bioinformatics]]
=== Category ===
=== Category ===
Bioinformatics
Bioinformatics


=== Program On ===
=== Program On ===
[https://github.com/vgteam/sequenceTubeMap GitHub]
Sapelo2


=== Version ===
=== Version ===
N/A
20230906


=== Author / Distributor ===
=== Author / Distributor ===
Line 15: Line 16:


=== Running Program ===
=== Running Program ===
 
This program, like others, should '''not''' be run on a submit node (''ss-sub2, ss-sub3, ss-sub4, etc''.). Instead, <u>run this program from within an interactive session</u>, which can be entered using the following command on a submit node:<syntaxhighlight lang="bash">
==== Initial Setup ====
Before a user can run this program, it first needs to be setup in a directory of the user's choosing such as the home or scratch directory.  
 
===== Enter Interactive Job =====
This program should be run from within an '''interactive job''', which can be started by issuing the following from a login node:<syntaxhighlight lang="bash">
interact
interact
</syntaxhighlight>
</syntaxhighlight>


===== Load Dependent Modules =====
==== Load Module ====
As of September 5<sup>th</sup>, 2023, the dependencies for this program are '''NodeJS''', '''NPM''', and '''vg'''. The '''NPM''' program is included in our '''NodeJS''' module, so the only modules necessary are '''NodeJS''' and '''vg''', which can be loaded with the following:
<syntaxhighlight lang="bash">
 
module load sequenceTubeMap/20230906-GCCcore-11.3.0
<u>'''NodeJS'''</u><syntaxhighlight lang="bash">
module load nodejs/18.12.1-GCCcore-11.3.0
</syntaxhighlight><u>'''vg'''</u><syntaxhighlight lang="bash">
module load vg/1.50.1
</syntaxhighlight>
</syntaxhighlight>
 
==== Obtain IP Address ====
===== Clone Repository =====
Obtain the IP address of the server that will host '''sequenceTubeMap''' for use in a later step:<syntaxhighlight lang="bash">
From within the directory that will serve to contain this project, clone the '''sequenceTubeMap''' repository:<syntaxhighlight lang="bash">
hostname -i
git clone https://github.com/vgteam/sequenceTubeMap.git
</syntaxhighlight>
 
===== Install NPM dependencies =====
This program depends on a few other programs from '''NPM'''. To install them, first enter into the '''sequenceTubeMap''' directory that was created when the repository was cloned in the previous step:<syntaxhighlight lang="bash">
cd sequenceTubeMap
</syntaxhighlight>Then, use '''NPM''' to install the additional programs into the project's directory:<syntaxhighlight lang="bash">
npm install
</syntaxhighlight>
 
===== Build the Frontend =====
Once the additional dependencies have been installed with '''NPM''', '''sequenceTubeMap''' will need to be built:<syntaxhighlight lang="bash">
npm run build
</syntaxhighlight>
</syntaxhighlight>


==== Starting the server ====
==== Starting the server ====
As long as the previous steps have been completed, the program can be started and used when needed. Starting the program is as simple as navigating to the directory in which it is located, and running the server.
Starting the program is as simple as defining the port and data path in environment variables and running the server. '''Make sure to provide the <u>absolute path</u> of your data.'''<syntaxhighlight lang="bash">
 
export SERVER_PORT=<port>; export MOUNTED_DATA_PATH=<data_path>; sequenceTubeMap
===== Enter Interactive Job =====
Unless already in an interactive job, it is necessary to enter into one before loading the modules and starting the server:<syntaxhighlight lang="bash">
interact
</syntaxhighlight>
</syntaxhighlight>


===== Load Dependent Modules =====
==== Configure SSH Tunnel ====
The same versions of the modules that were loaded when performing the initial setup for '''sequenceTubeMap''' should be loaded whenever attempting to run the software:
It will be necessary to use SSH tunneling to connect to the web frontend from within a web browser. Please note that '''this step is to be performed on your local computer'''. It is recommended to setup the SSH tunnel from a new, separate terminal.


<u>'''NodeJS'''</u><syntaxhighlight lang="bash">
'''<u>Note:</u>''' Successfully creating an SSH tunnel at the command line may cause the terminal to seem as though it froze or hung with no response, which is the expected behavior.
module load nodejs/18.12.1-GCCcore-11.3.0
</syntaxhighlight><u>'''vg'''</u><syntaxhighlight lang="bash">
module load vg/1.50.1
</syntaxhighlight>
 
===== Navigate to sequenceTubeMap =====
Unless already in the '''sequenceTubeMap''' directory, change to the location of that directory:<syntaxhighlight lang="bash">
cd /path/to/sequenceTubeMap
</syntaxhighlight>
 
===== Obtain IP Address =====
Obtain the IP address of the server that will host '''sequenceTubeMap''' for use in the next step:<syntaxhighlight lang="bash">
hostname -i
</syntaxhighlight>


===== Configure SSH Tunnel =====
===== SSH Tunneling from Mac or Linux =====
It will be necessary to use SSH tunneling to connect to the web frontend from within a web browser. Please note that '''this step is to be performed on your local computer'''. It is recommended to setup the SSH tunnel from a new, separate terminal. Currently, the program is hard-coded to run on port 3000, but this can be changed by editing a few files as demonstrated later on this page.
From your local terminal, issue the following command while making sure to replace '''HOST''' with the actual IP address obtained in the previous step, '''PORT''' with the port number used, and '''MyID''' with your UGA MyID:<syntaxhighlight lang="bash">
 
ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu
====== SSH Tunneling from Mac or Linux ======
From your local terminal, issue the following command while making sure to replace '''HOST''' with the actual IP address obtained in the previous step and '''MyID''' with your actual MyID:<syntaxhighlight lang="bash">
ssh -N -L 3000:HOST:3000 MyID@sapelo2.gacrc.uga.edu
</syntaxhighlight>
</syntaxhighlight>


====== SSH Tunneling from Windows ======
===== SSH Tunneling from Windows =====
Download the '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''', open a command window--the current directory of this command window should contain the ''plink.exe'' file--and execute the following command, replacing '''HOST''' with the actual IP address obtained in the previous step and '''MyID''' with your actual MyID:<syntaxhighlight lang="powershell">
plink -ssh -N -L 3000:HOST:3000 MyID@sapelo2.gacrc.uga.edu
</syntaxhighlight>


===== Launch the Program =====
Download the '''[https://the.earth.li/~sgtatham/putty/latest/x86/plink.exe plink program]''', open a command window--the current directory of this command window should contain the ''plink.exe'' file--and execute the following command, replacing '''HOST''' with the actual IP address obtained in the previous step, '''PORT''' with the port number used, and '''MyID''' with your UGA MyID:<syntaxhighlight lang="powershell">
To start the program, return to the terminal in which the interactive session is running, and execute the following command from within the '''sequenceTubeMap''' directory:<syntaxhighlight lang="bash">
plink -ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu
npm run serve
</syntaxhighlight>
</syntaxhighlight>


==== Connecting to the Server ====
==== Connecting to the Server ====
To connect to the server, simply open a web browser <u>on the computer connected to the SSH tunnel</u>, and navigate to http://localhost:3000 in the URL bar.
To connect to the server, simply open a web browser <u>on the computer connected to the SSH tunnel</u>, and navigate to [http://localhost:3000 http://localhost:PORT] in the URL bar, making sure to replace PORT with the actual port number used.


=== Running Program on Different Port ===
=== Example Usage ===
As of September 5<sup>th</sup>, 2023 '''sequenceTubeMap''' is hard-coded to run on port 3000. As a result, using an alternative port number will require manually changing a few files.


The following commands, if issued from within the '''sequenceTubeMap''' directory, will change the necessary files to use port 8942 instead:<syntaxhighlight lang="bash">
If the user, ''itd72797'', would like to host this program to visualize his data, he would first enter into an interactive session:<syntaxhighlight lang="bash">
sed -i "s/3000/8942/g" server.mjs
interact
sed -i "s/3000/8942/g" setupProxy.js
</syntaxhighlight>Second, he would load the corresponding module:<syntaxhighlight lang="bash">
sed -i "s/3000/8942/g" util/demo-data.js
module load sequenceTubeMap/20230906-GCCcore-11.3.0
</syntaxhighlight>If a port is used other than port 3000, use the same number when setting up SSH tunneling:<syntaxhighlight lang="bash">
</syntaxhighlight>Third, he would take note of the IP address of the server on which his interactive session is currently running:<syntaxhighlight lang="bash">
ssh -N -L 8942:HOST:8942 MyID@sapelo2.gacrc.uga.edu
hostname -i
</syntaxhighlight>Make sure to connect to the correct corresponding port number, http://localhost:8942, when connecting from a web browser as well.
</syntaxhighlight>If he has data in a directory at the file path ''/home/itd72797/testData'' and would like to host it on port ''8972'', he would execute the following from within the same interactive session:<syntaxhighlight lang="bash">
export SERVER_PORT=8972; export MOUNTED_DATA_PATH="/home/itd72797/testData"; sequenceTubeMap
</syntaxhighlight>He would then set up an SSH tunnel by issuing the following from a separate terminal <u>'''on his personal computer'''</u> using the IP address he identified earlier, the desired port, and his UGA MyID:<syntaxhighlight lang="bash">
ssh -N -L 8972:10.33.30.130:8972 itd72797@sapelo2.gacrc.uga.edu
</syntaxhighlight>To connect, he would open a browser window on his personal computer and navigate to http://localhost:8972 .


=== Documentation ===
=== Documentation ===

Latest revision as of 09:13, 8 September 2023

Category

Bioinformatics

Program On

Sapelo2

Version

20230906

Author / Distributor

vgteam

Description

"A JavaScript module for the visualization of genomic sequence graphs. It automatically generates a "tube map"-like visualization of sequence graphs which have been created with vg."

Running Program

This program, like others, should not be run on a submit node (ss-sub2, ss-sub3, ss-sub4, etc.). Instead, run this program from within an interactive session, which can be entered using the following command on a submit node:

interact

Load Module

module load sequenceTubeMap/20230906-GCCcore-11.3.0

Obtain IP Address

Obtain the IP address of the server that will host sequenceTubeMap for use in a later step:

hostname -i

Starting the server

Starting the program is as simple as defining the port and data path in environment variables and running the server. Make sure to provide the absolute path of your data.

export SERVER_PORT=<port>; export MOUNTED_DATA_PATH=<data_path>; sequenceTubeMap

Configure SSH Tunnel

It will be necessary to use SSH tunneling to connect to the web frontend from within a web browser. Please note that this step is to be performed on your local computer. It is recommended to setup the SSH tunnel from a new, separate terminal.

Note: Successfully creating an SSH tunnel at the command line may cause the terminal to seem as though it froze or hung with no response, which is the expected behavior.

SSH Tunneling from Mac or Linux

From your local terminal, issue the following command while making sure to replace HOST with the actual IP address obtained in the previous step, PORT with the port number used, and MyID with your UGA MyID:

ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu
SSH Tunneling from Windows

Download the plink program, open a command window--the current directory of this command window should contain the plink.exe file--and execute the following command, replacing HOST with the actual IP address obtained in the previous step, PORT with the port number used, and MyID with your UGA MyID:

plink -ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu

Connecting to the Server

To connect to the server, simply open a web browser on the computer connected to the SSH tunnel, and navigate to http://localhost:PORT in the URL bar, making sure to replace PORT with the actual port number used.

Example Usage

If the user, itd72797, would like to host this program to visualize his data, he would first enter into an interactive session:

interact

Second, he would load the corresponding module:

module load sequenceTubeMap/20230906-GCCcore-11.3.0

Third, he would take note of the IP address of the server on which his interactive session is currently running:

hostname -i

If he has data in a directory at the file path /home/itd72797/testData and would like to host it on port 8972, he would execute the following from within the same interactive session:

export SERVER_PORT=8972; export MOUNTED_DATA_PATH="/home/itd72797/testData"; sequenceTubeMap

He would then set up an SSH tunnel by issuing the following from a separate terminal on his personal computer using the IP address he identified earlier, the desired port, and his UGA MyID:

ssh -N -L 8972:10.33.30.130:8972 itd72797@sapelo2.gacrc.uga.edu

To connect, he would open a browser window on his personal computer and navigate to http://localhost:8972 .

Documentation

Please reference the program's GitHub page at https://github.com/vgteam/sequenceTubeMap for further reading.

System

64-bit Linux

Retrieved from "https://wiki.gacrc.uga.edu/index.php?title=SequenceTubeMap-Sapelo2&oldid=21523"