j5 installation

Users will not need to install j5 on their own computer, since the public web interface for the software is accessible at:

https://j5.jbei.org.


In addition, the j5 XML-RPC web-service allows users to utilize the full functionality of j5 through locally installed XML-RPC thin client software, without having to install and maintain j5 on their own machines.


Installation of the core j5 package:


These steps may require contacting your information technology support staff for assistance. The basic steps are to: 1) make sure that the software packages required for j5 are already properly installed (and accessible in your executable path, if applicable, see below), 2) download the j5 perl modules (you'll need to contact the j5 team in order to do this), 3) edit the j5 configuration perl modules to reflect the your local installation, and 4) place the j5 perl modules in to your local BioPerl package library directory structure (e.g. /Library/Perl/5.12/Bio/Tools/).


Installing required additional perl modules from CPAN (e.g. Text::CSV_XS)

Note that installing these required modules from CPAN is greatly facilitated with the following command:

sudo perl -MCPAN -e 'install Text::CSV_XS'

which will install the Text::CSV_XS perl module(s) automatically. The "Text::CSV_XS" can be substituted with any other perl module that you would like/need to install.


Executables that must be accessible in the search PATH:

The BLAST bl2seq executable (e.g. blastn)

The Primer3 executable (e.g. primer3_core)


The j5 perl modules should be placed in the same directory as the BioPerl package, (e.g. /usr/share/perl5/Bio/Tools/).

Contained within this Bio/Tools/ BioPerl directory should be the following (in addition to the other BioPerl modules):

j5.pm - the core j5 perl module

j5/Automation.pm - a j5 perl module that manages downstream automation processes

j5/Auxiliary.pm - a j5 perl module that manages auxiliary processes

j5/Configuration.pm - a j5 perl module that configures the j5 package

j5/XML_RPC.pm - a j5 perl module that manages XML-RPC web-services


The j5/Configuration.pm perl module must be modified as following:

The lines containing

PATHTOBLASTANDPRIMER3 => ":/usr/local/ncbi/blast/bin:/usr/share/primer3/bin"

PATHTOPRIMER3EXECUTABLE => "/usr/share/primer3/bin/primer3_core",

J5_WWW_DIRECTORY => '/var/www/j5'

should be modified to reflect the paths to the BLAST and Primer3 directories, to the primer3 executable, and to the path to the j5 server www directory (optional, see below).


Installation of the stand alone command-line j5 interface (optional):


The basic steps are to: 1) download the command-line executable j5 perl-scripts (see the list below, you'll need to contact the j5 team in order to do this), and 2) add these perl-scripts to your executable path.


The following perl scripts that call the j5 software package must be accessible in your executable PATH:

j5_SLIC_Gibson_CPEC.pl

j5_SLIC_Gibson_CPEC_zip.pl

j5_combinatorial_SLIC_Gibson_CPEC.pl

j5_combinatorial_SLIC_Gibson_CPEC_zip.pl

j5_golden_gate.pl

j5_golden_gate_zip.pl

j5_combinatorial_golden_gate.pl

j5_combinatorial_golden_gate_zip.pl

j5_mock_zip.pl

j5_combinatorial_mock_zip.pl

j5_condense_assembly_files.pl

j5_condense_assembly_files_zip.pl

j5_distribute_pcr_reactions.pl

j5_distribute_pcr_reactions_zip.pl

j5_distribute_split_and_pool_pcr_reactions.pl

j5_distribute_split_and_pool_pcr_reactions_zip.pl

jbeiseq_to_genbank.pl

genbank_to_jbeiseq.pl

SBOLXML_to_genbank.pl

genbank_to_SBOLXML.pl


If you would like to call the j5 XML-RPC web-services from the command-line, the following perl scripts should also be accessible in your executable PATH:

j5_xml_rpc_client_create_new_j5_session_id.pl

j5_xml_rpc_client_get_last_updated_user_files.pl

j5_xml_rpc_client_design_assembly.pl

j5_xml_rpc_client_condense_multiple_assembly_files.pl

j5_xml_rpc_client_design_downstream_automation.pl

j5_xml_rpc_client_convert_SBOLXML.pl

j5_xml_rpc_client_return_error_message.pl


Installation of the simplified web page j5 interface, DeviceEditor graphical j5 interface, j5 XML-RPC web-services, and stand-alone VectorEditor (optional):


These steps may require contacting your information technology support staff or web server administrators for assistance (especially as it pertains to setting up file and executable permissions, etc.). The basic steps are to: 1) download the j5 web-server directory (you'll need to contact the j5 team in order to do this), 2) set up the web server configuration to allow execution of the various perl-cgi scripts (e.g. j5_entry_form.pl), and 3) edit the various perl-cgi scripts code to reflect the your local installation.


The j5 web-server directory should be placed at the root of the path accessible by the web server, (e.g. /var/www/j5).

Contained within this directory should be the following:

DeviceEditor/ - a directory containing the DeviceEditor software

DeviceEditor_manual/ - a directory containing the DeviceEditor manual

SpectaclesEffects.png - the DeviceEditor logo

VectorEditor/ - a directory containing the DeviceEditor software

VectorEditor_Large.png - the VectorEditor logo

bin/ - a directory containing the j5 perl-cgi scripts.

copyright.html - a page containing j5 copyright information

index.html - the root page of the j5 website

j5_and_DeviceEditor_Demo_Movie.mov - the j5/DeviceEditor/VectorEditor demonstration movie

j5_logo_simple.png - the j5 logo

j5_logo_small.jpg - a smaller version of the j5 logo

j5_sessions_table.csv - a CSV file containing the list of j5 sessions

j5_set_user_password.pl - an administrative perl-script for creating/modifying/deleting j5 user accounts

j5_users_table.csv - a CSV file containing the list of j5 users

license.html - a page containing j5 software license information

manual/ - a directory containing the j5 user manual

usr/ - a directory where all user files will be stored


The j5 web-server cgi-bin directory (e.g. /var/www/bin) should contain the following:

Configuration.pm - a perl module that largely configures the j5 web server

CookieManager.pm - a perl module that manages browser cookies

UserManager.pm - a perl module that manages j5 user accounts

Utils.pm - a perl module with various utilities

WebPageHelper.pm - a perl module that helps manage cgi web pages

deviceeditor.pl - a perl-cgi script that is used to call the DeviceEditor software

index.pl - a perl-cgi script that is used to direct the user to either j5 or DeviceEditor

j5_check_for_assembly_piece_incompatibilities.pl - a perl-cgi script that is used to check for assembly piece incompatibilities in multi-threaded mode

j5_entry_form.pl - a perl-cgi script that is used as a web form-based user interface for j5

j5_xml_rpc.pl - a perl-cgi script that implements a j5 XML-RPC web-service

login.pl - a perl-cgi script that is used to handle user logins

logout.pl - a perl-cgi script that is used to handle user logouts

sbol_converter_entry_form.pl - a perl-cgi script that is used as a web form-based user interface for j5's SBOL XML <-> GenBank conversion utility

vectoreditor_sequence.pl - a perl-cgi script that is used to interface DeviceEditor with VectorEditor

verify.pl - a perl-cgi script that is used to verify that a user has valid credentials


The (Apache) web-server configuration file (e.g. etc/apache2/httpd.conf) must be set to allow +ExecCGI in the directory containing the j5 perl-cgi scripts (e.g. /var/www/j5/bin).


the j5_set_user_password.pl administrative perl-script that must be modified to fit the local installation:

The line containing

use lib ('/Library/Perl/5.16');

should be modified to point to the location of the BioPerl library on your web-server.


Portions of the bin/Configuration.pm perl module that must be modified to fit the local installation:

The line containing

HOSTNAME => 'j5.jbei.org',

should be modified to reflect the host name of your web-server


The line containing

J5_WWW_DIRECTORY => '/var/www/j5',

should be modified to point to the location of the j5 directory on your web-server


The line containing

HOST_URL_J5_ROOT_DIR => '/',

should be modified to point to the URL root directory location of j5 directory on your web-server


The line containing

BIOPERL_LIB_DIRECTORY => '/usr/share/perl5',

should be modified to point to the location of the BioPerl library on your web-server


The line containing

PATHTOBLASTANDPRIMER3 => ":/usr/bin/ncbi-blast-2.2.29+/bin:/usr/bin",

should be modified to include the executable paths of BLAST and Primer3 on your web-server


The line containing

USERS_MANUAL_URL => 'j5.jbei.org/j5manual',

should be modified to point to the j5 manual on your web-server


The line containing

REQUEST_ACCOUNT_MESSAGE => 'Send an email to Nathan Hillson (<a href="mailto:njhillson@lbl.gov">njhillson@lbl.gov</a>) for a new account (or forgotten passwords).',

should be modified to email the systems (or j5) administrator for your web-server


The line containing

INVALID_CREDENTIALS_MESSAGE => " (new accounts/temporary passwords should first log in <A HREF=\"https://j5.jbei.org/index.php?title=Special:Userlogin\">here</A>).",

should be modified to set the desired response to invalid user credentials


Each of the perl-scripts (deviceeditor.pl, index.pl, j5_entry_form.pl, j5_xml_rpc.pl, login.pl, logout.pl, sbol_converter_entry_form.pl, vectoreditor_sequence.pl, verify.pl) must be modified as following:

The line containing

use lib ('/var/www/j5/bin/');

should be modified to point to the location of the /bin directory on your web-server


Managing j5 web-server user accounts

User access to j5/DeviceEditor (web-services) is controlled through password validation, in addition to any desired web-server enforced firewall(s). Users will need to have an account set up for them (the requisite information includes a username, their full name, and a selected password). The administrative perl-script j5_set_user_password.pl is used to facilitate this process.


In the j5 directory on the web-server (e.g. /var/www/j5), with administrative privileges, run the following command:

sudo ./j5_set_user_password.pl j5_users_table.csv

This will execute the administrative perl-script and prompts will direct you to create a new user account, change the password of an existing user, or delete an existing user from the system.