SequenceTubeMap-Sapelo2: Difference between revisions

From Research Computing Center Wiki
Jump to navigation Jump to search
m (Isaiah moved page SequenceTubeMap to SequenceTubeMap-Sapelo2: Fix name)
(Instead of documenting how to set up the program, this page now simply shows how to use the already set up program.)
Line 3: Line 3:


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


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


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


=== Running Program ===
=== Running Program ===
 
This program, like other 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 setting the environment variables that define the port and data to, and running the server. '''Make sure to pass the <u>absolute path</u> to 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">
===== SSH Tunneling from Mac or Linux =====
module load nodejs/18.12.1-GCCcore-11.3.0
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">
</syntaxhighlight><u>'''vg'''</u><syntaxhighlight lang="bash">
ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu
module load vg/1.50.1
</syntaxhighlight>
</syntaxhighlight>


===== Navigate to sequenceTubeMap =====
===== SSH Tunneling from Windows =====
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 =====
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.
====== 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>
====== 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">
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
plink -ssh -N -L PORT:HOST:PORT MyID@sapelo2.gacrc.uga.edu
</syntaxhighlight>
 
===== Launch the Program =====
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">
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.
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">
 
interact
The following commands, if issued from within the '''sequenceTubeMap''' directory, will change the necessary files to use port 8942 instead:<syntaxhighlight lang="bash">
</syntaxhighlight>Second, he would load the corresponding module:<syntaxhighlight lang="bash">
sed -i "s/3000/8942/g" server.mjs
module load sequenceTubeMap/20230906-GCCcore-11.3.0
sed -i "s/3000/8942/g" setupProxy.js
</syntaxhighlight>Third, he would take note of the IP address of the server on which his interactive session is currently running:<syntaxhighlight lang="bash">
sed -i "s/3000/8942/g" util/demo-data.js
hostname -i
</syntaxhighlight>If a port is used other than port 3000, use the same number when setting up SSH tunneling:<syntaxhighlight lang="bash">
</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">
ssh -N -L 8942:HOST:8942 MyID@sapelo2.gacrc.uga.edu
export SERVER_PORT=8972; export MOUNTED_DATA_PATH="/home/itd72797/testData"; sequenceTubeMap
</syntaxhighlight>Make sure to connect to the correct corresponding port number, http://localhost:8942, when connecting from a web browser as well.
</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:<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 ===

Revision as of 08:27, 7 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 other 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 setting the environment variables that define the port and data to, and running the server. Make sure to pass the absolute path to 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.

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:

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 and MyID with your actual 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:

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=21508"