PeptideShaker Online Setup
As its developers state in the main Galaxy web portal:
Galaxy is an open source, web-based platform for data intensive biomedical research.
Galaxy's main contribution has been to establish a common framework in which different applications (called "Galaxy tools" in Galaxy context, which may be written in different programming languages, with different dependencies and requirements) can work together transparently to the user.
PeptideShaker Online use this ability to coordinate different Galaxy tools in order to process complex data and give the results back to the frontend to be shown to the user in the best possible way independently of Galaxy's own interface.
In order to process the user's data we need to
- Have a properly configured and running Galaxy instance.
- Install the Galaxy tools required by PeptideShaker Online.
Although Galaxy manages by itself its dependencies when it is being installed and most operating systems already include the most basic Galaxy dependencies, before installing Galaxy it is convenient to check that the server already has the following components installed:
- Python 3.6 or higher and its development packages (usually called python3-dev).
- Virtualenv.
The Galaxy team has created a step-by-step guide to install and configure a Galaxy instance into a local server:
Note: Although the procedure recommends to install the latest Galaxy version, all tools required by PeptideShaker Online are able to work on any Galaxy version 19.05 or higher.
Thereby, when there is already a Galaxy instance running, it can be safely reused in order to execute the entire PeptideShaker Online workflow.
Please note that if the OS is newer than 2019 and there are errors related to Python packages when running run.sh, they may be caused by some missing python2 package on the system. It is then recommended to install python2 and pip2 and try again. Python2 is deprecated but some components may still use it.
In order to comprehensively manage the installed Galaxy instance it is necessary to create an admin user. It is easy but it requires a couple of steps:
- Access to the instance login page and click on Don't have an account? Register here link.
- Fill in all the information and click on Create. It is necessary to remember the email and password used for the registration.
Now there will be a new user available in the Galaxy instance, but it only has standard user privileges. In order to manage the instance it is necessary to register it as an admin user:
- Change the galaxy.yml.sample file (it is located into <galaxy_root_folder>/config folder). However, the recommended procedure is to always keep a copy of all .sample files, so the best procedure is to just duplicate galaxy.yml.sample into another file named galaxy.yml which will be the modified one.
Opening this file and looking for a key (it is usually commented, so it will need to be uncommented) like:
#admin_users:
it will be necessary to add there the email of the instance admin user.
- Save the changes and restart the Galaxy instance to make the changes available. To verify that all changes were successful, when login with the user name/email and password a new Admin menu will be available in the top menu.
PeptideShaker Online requires a set of Galaxy tools installed into the Galaxy instance in order to execute its calculations. These tools are:
- FastaCLI (Appends decoy sequences to FASTA files)
- Thermo Raw File Converter (official Galaxy tool name: thermo_raw_file_converter)
- PeptideShaker (officially peptideshaker)
- SearchGUI (included into PeptideShaker Galaxy tool package)
- moFF (officially proteomics_moff)
- Convert delimiters to TAB (officially convert_characters)
Galaxy default listening port is 8080. If this port is already in use by another application into the same server (as it may happen if Galaxy is installed on the same server as Tomcat, whose default listening port is 8080 as well), it is necessary to change the port used by the first application or by Galaxy itself.
Changing Galaxy's default listening port requires to edit galaxy.yml file again. Opening it, there will be a line with a content similar to
http: 127.0.0.1:8080
in the uwsgi section. It is the correct place to introduce the new port Galaxy will listen to.
After saving the file with the modification, it is required to restart Galaxy in order to enable the changes.
By default, Galaxy tools only use one local core when executing. PeptideShaker Online-related tools may take advantage of multiple CPUs (and many other features supported by Galaxy), but in order to be used, a couple of extra configuration steps are needed.
The procedure mostly depends on your backend architecture, so it is recommended to follow the official documentation carefully in order to choose the configuration that fits best to your needs.
-
Main document about job configuration: Jobs configuration
-
Details about number of cores used: Galaxy slots
-
Cluster configurations: Cluster configuration
It must be highlighted that PeptideShaker Online-related Galaxy tools names must be used (listed above) when doing reference to PeptideShaker Online-related processes.
All of them are publicly available in the Galaxy Tool Shed. The recommended versions to be used are always the latest available.
The procedure to install them, searching for their official Galaxy tool names (listed previously) in the main Galaxy Tool Shed, is fully described in the official Galaxy documentation here:
It is necessary to remember to be logged into the Galaxy instance as an admin user in order to be able to access to this privileged operation.
PeptideShaker Online requires a MySQL or MariaDB (its open source counterpart) database in order to run. Using the latest available version (MySQL 8 or MariaDB 10) is always recommendable, although both MySQL 5.7 and MariaDB 5.5 have been successfully tested.
As it happens with Tomcat, depending on the target OS (i.e.: Microsoft Windows, or Linux/MacOs), there are different steps to follow and different packages to download, and many Linux distributions provide precompiled, fully supported binaries ready to be installed. Thereby, as far as they meet PeptideShaker Online requirements, they should be preferred over any other sources.
PeptideShaker Online is a Java web application based on the Vaadin framework version 7.7.26 It internally uses Java Servlet version 3.0, and requires a Java Runtime Environment properly configured and a Servlet container compatible with Java Servlets 3.0 specification.
Specifically, PeptideShaker Online backend has been tested using JRE 8 and Apache Tomcat 8.0 and 9.0, although it will work with more recent JRE and other Servlet containers which meet Servlet 3.0 specifications. Please note that, as Apache Tomcat requires a Java SE Development Kit (JDK), which also includes the JRE, it is easier to just install JDK 8 or higher in order to satisfy Apache Tomcat and PeptideShaker Online Java requirements.
JREs and JDKs may be downloaded and installed from Oracle or from the open source project OpenJDK, and many Linux distributions include precompiled packages ready to be downloaded and installed (these are usually the easiest to install).
The Apache foundation provides a guide with all different Tomcat versions and their specifications in order to better clarify Java required versions, Servlet supported specifications and others:
However, last available Apache Tomcat (stable) versions are always recommended.
Note that, depending on your OS (i.e.: Microsoft Windows, or Linux/MacOs), it will be necessary to follow different steps and download different Apache Tomcat packages of; furthermore, many Linux distributions provide precompiled, fully supported Tomcat binaries ready to be installed: as far as they meet PeptideShaker Online requirements, they should be preferred over any other sources.
Once Apache Tomcat is properly running on the target server, it is time to deploy PeptideShaker Online. It can be done manually by copying the PeptideShaker Online WAR file to Tomcat's webapps folder. Depending on Tomcat configuration, it will automatically detect the war file and deploy it, or it may require restarting Tomcat.
This manual procedure is the most secure but it may not be practical. Tomcat provides an independent package called tomcat-admin (or similar, depending on the OS and distribution) which, when installed, provides a graphical manager application (easily accessible via the relative url /manager) which greatly facilitates remote uploading of new applications to tomcat. In order to use and secure it you have to edit the tomcat-users.xml file, adding to it one user with manager-gui and admin-gui roles properly associated and enabled.
Note that the graphical manager has a default limit of 50mb for uploading WAR files. As PeptideShaker Online WAR file is bigger than 50mb, it is necessary to increase this limit by modifying the manager's web.xml file, located at
<tomcat-root-folder>/webapps/manager/WEB-INF/web.xml
Editing this file and moving to its multipart-config element, the value of its max-file-size and max-request-size subelements has to be changed to a bigger size than PeptideShaker Online WAR file size. Restarting Tomcat after saving the changes will be necessary to make them available.
In order to configure the PeptideShaker Online war file, access to the configuration file config.json will be needed. WinRAR archiver may be used to access and update the file.
The configuration file is located in VAADIN folder
...peptideshaker-online/WEB-INF/config.json
After locating the file, these fields will have to be updated:
"galaxyServerUrl": ""
PeptideShaker Online application has to know Galaxy's URL in order to connect to it.
"testUserAPIKey": ""
We recommend creating a public user using a general API key (see Galaxy user key) so that users can anonymously access the public user's account. Please note that the data used in this account will be public and shared between all users.
"url": ""
Database URL; the default url for MySQL database is "jdbc:mysql://localhost:3306/".
"password": ""
Database password.
"userName": ""
Database username.
"dbName": ""
Database name.
"maxusernumb": 5
The maximum number of concurrent users; the default is five but it can be increased depending on the server capabilities.
In addition, you will need to update the versions of the tools
"MOFF_TOOL_ID": "toolshed.g2.bx.psu.edu/repos/galaxyp/proteomics_moff/proteomics_moff/2.0.3.0"
"MOFF_TOOL_Version": "2.0.3.0"
"CONVERT_CHARACTERS_TOOL_ID": "Convert characters1"
"THERMO_RAW_CONVERTOR_TOOL_ID": "toolshed.g2.bx.psu.edu/repos/galaxyp/thermo_raw_file_converter/thermo_raw_file_converter/1.2.3+galaxy0"
"THERMO_RAW_CONVERTOR_TOOL_VERSION": "1.2.3+galaxy0"
"SEARCHGUI_TOOL_VERSION": "4.0.41+galaxy1"
"SEARCHGUI_TOOL_ID": "toolshed.g2.bx.psu.edu/repos/galaxyp/peptideshaker/search_gui/4.0.41+galaxy1"
"fasta_cli_TOOL_VERSION": "4.0.41+galaxy1"
"fasta_cli_TOOL_ID": "toolshed.g2.bx.psu.edu/repos/galaxyp/peptideshaker/fasta_cli/4.0.41+galaxy1"
"BUILD_LIST_TOOL_ID": "__BUILD_LIST__"
"BUILD_LIST_TOOL_VERSION": "1.0.0"
"PEPTIDESHAKER_TOOL_VERSION": "2.0.33+galaxy1"
"PEPTIDESHAKER_TOOL_ID": "toolshed.g2.bx.psu.edu/repos/galaxyp/peptideshaker/peptide_shaker/2.0.33+galaxy1"