Setting up Web Persephone Client

Note

The settings discussed below are pre-configured in the Docker image we provide. The steps on this page are needed only if you are installing Persephone components by yourself or if you would like to change the default parameters of the API server.

The installation of Web Persephone client is simple - unpack the archive with the server binaries, modify the configuration files to connect to proper database and the search engine, and start the server.

In case of the web version, the main server application, called WebCerberus, will perform regular operations of a web server, so you do not need to have any other web server to serve the pages - WebCerberus will do it for you.

1. Unpack the archive with binaries to some directory

A typical command on linux would be:

tar -xf WebPersephoneApp_8.6.8756.tgz

2. Prepare the connection string to the database.

The connection string itself is an encrypted string in EZconnect format: username/password@serverUrl:port/serviceName, for example, scott/tiger@persephonedb.company.com:3306/prod.

Encrypt this string using the program cipher supplied with PersephoneShell (as with all other programs, use Mono to launch on linux).

mono cipher.exe -e -c scott/tiger@persephone.company.com:3306/prod

It will produce the encrypted connection string. With the switch -c, the result will be also copied to the clipboard.

3. Modify the file SelfHostingWebCerberus.exe.config

Update the connection string:

<connectionStrings>
<clear />
<add name="Default" providerName="MySql.Data.MySqlClient" connectionString="connection string here" />
<add name="System" providerName="MySql.Data.MySqlClient" connectionString="connection string here" />
</connectionStrings>

Replace the highlighted text with the text in the clipboard. Remember, the first connection (Default) is used for read operations, and the second (System) is for writing into the database. Most of the time, these connections are the same, but they can be different if you are using read replicas.

Find the section for Solr search index engine:

<SolrSearchSettings Enabled="true" ServerUrl="http://localhost:8983/solr" CoreName="prod" />

Provide the name of the Solr core. See the configuration of the Solr search index. You can reuse the same server as the one used for the Windows version.

Adjust BLAST settings.

<BlastSettings>
<NcbiBlast MultipleSubjects="true" BlastDbFolder="/data/blast/prod" ProgramDirectory="/bin/blast" TimeoutMinutes="2" TempDirectory="{TEMP}" MaxFileSize="10000000" MaxSubjectLength="4000MB"/>
</BlastSettings>

Configure the user disk settings

If you want the end users to upload their own data, provide information on the corresponding disk space and login options.

The user's disk quota is applied to the data processed and stored on the server. For example, for the uploaded FASTA files the needed disk space is just 25% of the original size due to compression.

For a simple scenario, where all users have the same disk quotas (for example, 200 MB), use the following construct:

Here, you can control how much disk space you want to allow for all users. A separate page will describe advanced settings that allow the of different disk quotas for different users.

Configure the user login options

The users can log in using different mechanisms, such as email authentication or using OpenId.

Based on which providers in the section above are enabled, the web application will display a choice for entering the login credentials:

Note that to preserve the custom changes made to the configuration file, it is recommended to extract the changes and save them in a separate file called custom.config. It's far more succinct and simpler to modify compared to the lengthy XML file used for the primary configuration.

Using email authentication

Users can register using their email address. In the process of registration, they will also provide their password. In communication with the users, Web Persephone will send emails to the registered address. In this case, we need to configure the mail server settings. Here is an example using Gmail SMTP settings:

Use cipher to encrypt the password, this is required.

In case of using Gmail as the mail server, a special password generated by Gmail will be needed. Register your device that will be contacting the service and use the generated password. More details are available here: https://www.lifewire.com/get-a-password-to-access-gmail-by-pop-imap-2-1171882

Add configset to Solr

If you plan to accommodate registered users who will upload their own data, you will need to add a special configset to Solr server, so that the uploaded data get indexed and is available for search.

Unpack the archive with the configset files to {PATH_TO_SOLR_SERVER}/server/solr/configsets/persephone.

This will create a sub-folder with the path similar to /usr/bin/solr/server/solr/persephone/conf.

Running Web Persephone

Start the server the same way as the API-server for Windows:

mono SelfHostingWebCerberus.exe

This will run the server on port 1337 by default. If you want to change the port add a parameter on the command line. For example, if you want to change the port to 1338, run (note the closing slash):

mono SelfHostingWebCerberus.exe "http://*:1338/"

To start the web application, navigate to the URL pointing to the server in your browser. Make sure that this address is listed in the license for the application.

For example, http://localhost:1337 or to a domain assigned to the server's IP address: http://persephone.company.com:1337

When running the server under http:// please make sure to include the following highlighted instruction to the configuration file SelfHostingWebCerberus.exe.config:

This will allow saving the cookies (used for the user authentication) in unsecured hosting environment, such as http://.