Skip to content

Private Hosting

Jump to bottom
Dain Brademan edited this page Mar 25, 2019 · 3 revisions

Overview

The documents and code used to run IPSA can easily be ported over to a private server instance. This section of the wiki is meant to guide the user through the process of uploading the source code, configuring the database, and updating configuration files.

Alternatively, refer to the precompiled Docker image located here on the GitHub Wiki

Contents

Instructions

Server Configuration

IPSA was developed and tested on a XAMPP server and is currently hosted on a server running a LAMP stack. XAMPP is an acronym for:

X - Cross-operating system, i.e. Windows, Linux, ect.
A - Apache HTTP web server
M - MySQL database
P - PHP
P - Perl (not utilized in IPSA)

Minimum Hardware & Software Requirements

  • OS Windows or Linux
  • CPU - 2 cores, 2.4 Ghz
  • RAM - 2 GB
  • Storage - 150 GB
  • Apache - Version 2.3 or later.
  • PHP environment - Version 5.2 or higher. Required for PHP Data Object support.
  • Note - IPSA runs on a 1 vCPU, 1 GB RAM virtual machine. However, it didn't behave nicely under heavy use. May be fine for an individual user.

Suggested Hardware & Software Requirements

  • CPU - 4 cores, 2.4 Ghz
  • RAM - 4 GB
  • Storage - 500 GB
  • Apache - Version 2.4 or greater.
  • PHP environment - Version 7.0+.

Implementing Source Code

IPSA can be ported to a new server easily, simply requiring the files contained in this repository to be transferred to the server URL's root directory / document root. Please refer to your web server distribution's documentation to determine exactly where this directory resides.

  • The document root potentially can be found in the Apache configuration file (named my.conf or httpd.conf).

The following files must be placed into the document root for IPSA to function:

  • .htaccess - configuration file used by Apache to define navigation behavior.
  • index.html - default landing page. Forwards browser to PeptideAnnotator.html.
  • PeptideAnnotator.html - The Single Spectrum Annotator.
  • BulkDataUpload.html - File upload page.
  • VisualizeUploadedData - Annotator for uploaded data.
  • Support directory - Contains all dependencies and scripts for the website.

All scripts and dependencies (not including server setup) are provided locally in the '%DocumentRoot%/support/' folder.

Navigating to IPSA

Assume IPSA is being hosted on a server with a public-facing IP address 50.100.150.200 and the source code has been moved to the directory /%DocumentRoot%/IPSA.

IPSA, in this theoretical situation, be accessed by navigating to the URL "50.100.150.200/IPSA".

Database Configuration

We strongly recommend using a MySQL database to store uploaded data for IPSA. While the PHP Data Objects used to conduct database transactions theoretically work with many different databases, IPSA's SQL queries specific target MySQL's syntax and conventions. Using a different backend may cause errors.

We provide a SQL dump in this repository which can be directly imported into a new MySQL environment. The database defaults to the name 'bulk_spectra'. This database name can be changed by editing the 'CREATE DATABASE...' statement in the beginning of the SQL dump.

The database structure is fairly simple, consisting of three tables: 'identifications', 'spectra', and 'mods'. These table names should not be changed.

Configuration File Edits

Several configuration files and scripts need minor edits to ensure compatibility with the new web server. We will walk through the necessary changes in this section.

PHP Environment Changes

By default, the PHP environment is severely restrictive towards file upload size and time limits for script execution. As mass spectrometry data files can be gigabytes large and take minutes to process, several variables in the PHP configuration file need to be updated.

  • The configuration file is a text file called "PHP.ini". It's location can be found by running the "phpinfo();" command in a php file, or via commandline using "php -i".

  • Open the php.ini file in a text editor and change the following settings and save.

    • Set upload_max_filesize. Change it's value to above the maximum filesize you expect to upload, e.g. "4G" (4 GB).
    • Set max_execution_time to something along the lines of 600 (10 minutes). File upload and bulk processing may time out if this number is too small.
    • Set max_input_time to the same as max_execution_time.
    • Set memory_limit to "2G". Otherwise PHP may run out of memory and error out.

  • (optional) - upload_tmp_dir may need to be updated depending on security settings on your server. If php scripts don't have read permissions to this directory, files cannot be parsed for the MySQL database.

Restart the Apache server when done.

IPSA Configuration File Edits

Two PHP files in the IPSA source code need to be edited to ensure compatibility with the new server setup, config.php and UploadHandler.php.

Config.php Edits

Config.php contains critical information used to access the MySQL database and to process uploadable and downloadable files. The following lines must be updated:

  • Line 3 - Set the variable $db to the MySQL database name. Probably 'bulk_spectra' unless changed.
  • Line 4 - Set the variable $username to a valid MySQL user account. You may need to create one if it does not yet exist.
  • Line 5 - Set the variable $password to the MySQL user account's password.
  • Line 15 - Set the variable $supportFolder to the absolute path of IPSA's support folder. E.g. "C:/XAMPP/IPSA/support/"

Save and close the file when you're done.

UploadHandler.php Edits

UploadHandler.php is a script which manages the transfer of uploaded files from the server's default location to "%DocumentRoot%/support/Upload Folder/".

Similar to line 15 in config.php, change the $basePath variable to the absolute path to IPSA's support folder on your system.

  • Line 15 - Set the variable $basePath to the absolute path of IPSA's support folder. E.g. "C:/XAMPP/IPSA/support/"

Save and close the file when you're done.

Tutorials

Hosting IPSA

Clone this wiki locally