The stand-alone server SelfHostingCerberus is a new alternative to the older web application hosted by IIS. It does not require any pre-installed web server like IIS or Apache. The installation procedure for this self-hosting version is much simpler than the set up for the older Cerberus server, so we highly recommend using SelfHostingCerberus.

Unpack the binaries of the stand-alone API server to some directory. The configuration file SelfHostingCerberus.exe.config should contain the encrypted database connection strings.

In case of Oracle:

<!-- Database connection strings; the "Default" key is required.
       These connection strings must be encrypted using the same mechanism as in Persephone. -->
  <connectionStrings>
    <clear />
     <!-- Oracle database -->
     <add name="Default" connectionString="xxxxxxxxxx" />
     <add name="System" connectionString="xxxxxxxxxxx" />
  </connectionStrings>

In case of MariaDb:

<!-- Database connection strings; the "Default" key is required.
       These connection strings must be encrypted using the same mechanism as in Persephone. -->
  <connectionStrings>
    <clear />
     <!-- MariaDb database -->
     <add name="Default" providerName="MySql.Data.MySqlClient" connectionString="xxxxxxxxxx" />
     <add name="System" providerName="MySql.Data.MySqlClient" connectionString="xxxxxxxxxxx" />
  </connectionStrings>

Important: the line <clear /> should be the first line in the list of connectionStrings.

Enter the main read-only database connection string as shown in the example below. (Replace the text highlighted in yellow with an actual encrypted connection string.) This string is what tells Cerberus how to connect to your database and fetch the genomic data.

     <add name="Default" connectionString="xxxxxxxxxx" />

Enter the system connection string for your Cerberus server as shown in the example below. Please note that the connection will be used for logging performance, usage data and saving user's bookmarks. This connection must be writable on your database server; however, it does not need to be fast, since the data will be written in the background without affecting the user experience. It is common to use the same connection string for Default and System connections.

     <add name="System" connectionString="xxxxxxxxxxx" />

If you plan to run the server on Linux, please install Mono framework (version 4.0 or later) first. The server can be started from the OS command line as:

Windows:

SelfHostingCerberus http://localhost:80/

Linux

mono SelfHostingCerberus.exe http://localhost:80/

or

mono SelfHostingCerberus.exe "http://*:80/"


Important:

Note the closing slash at the end of the URL parameter.

This will start the server that will listen to the port 80, which is normally open by default for regular web users. Please navigate to http://localhost to see the list of API functions. If necessary, change port 80 to some other number. (When run without parameter, the self-hosting Cerberus will listen to the port 1337). Please make sure that the port is also open for your clients.

Note

It is possible to run several Cerberus instances on different ports simultaneously. For example, the production instance can run on port 80 while the instance for testing can use port 8080 or 443. Please ensure that each instance has its own folder for cached data.

The rest of the configuration file deals with caching and the search index.

 <!--  
    Disk-based cache for genome DNA.
    All parameters except for CacheDirectory are optional.

          Enabled:    If "false", disk cache will be disabled, and all of the other parameters
                      will be ignored. Default is "true".

    CacheDirectory:    The directory that will contain cached DNA sequences.
                      The token {TEMP} will be replaced by the current Windows temp folder.
                       
    MaxSizeOnDiskMb:   Maximum size of the cache files on disk, in megabytes. When the cache
                      exceeds this size, oldest entries will be removed.

    ChunkFileSizeKb:   Maximum size of a single sequence chunk, in kilobytes. DNA sequences
                      will be split up into chunks of roughly this size.
   -->
  <DiskCacheSettings Enabled="true" CacheDirectory="{TEMP}/cerberus/dna_cache" MaxSizeOnDiskMb="4096" ChunkFileSizeKb="2048" />
 
  <!--
    Search engine configuration.
    All parameters except for IndexDirectory are optional.
   
           Enabled:    If "false", search engine will be disabled, and all of the other parameters
                       will be ignored. Default is "false".
   
    IndexDirectory:    The directory that will contain search index data.
                       The token {TEMP} will be replaced by the current Windows temp folder.
   
        UpdateMode:    Update mode can be APPEND or OVERWRITE
                       APPEND:
                          Appends any new items (markers, genes, QTLs, etc.) to the index.
                          Existing items will be left unchanged.
                       OVERWRITE:
                          Deletes existing indexes, and re-creates them using the new items.
   -->
  <SearchEngineSettings Enabled="true" IndexDirectory="/data/searchIndex" UpdateMode="OVERWRITE" />
 
  <!--
    Disk-backed cache for track data.
   
       
           Enabled:    If "false", disk cache will be disabled, and all of the other parameters
                       will be ignored. Default is "true".
                       
    CacheDirectory:    The directory that will contain cached tracks.
                       The token {TEMP} will be replaced by the current Windows temp folder.
                   
    MaxSizeOnDiskMb:   Maximum size of the cache files on disk, in megabytes. When the cache
                       exceeds this size, oldest entries will be removed.                      
  -->
 
  <TrackCacheSettings Enabled="false" CacheDirectory="{TEMP}/cerberus/track_cache" MaxSizeOnDiskMb="1024" />


For now, we recommend to enable the disk cache (for DNA sequences) and disable the track cache (it requires coordination with the database table DATA_VERSION, which is an advanced topic not yet documented here).

As for the search engine, please read a separate page on configuring Lucene.

Setting up SelfHostingCerberus as a daemon on linux

Normally, the server should run under some sort of terminal multiplexer, such as tmux (https://en.wikipedia.org/wiki/Tmux). This would ensure that the program will not terminate even when the terminal session is closed.

In case of using tmux, first enter a terminal session by typing

tmux

on the command prompt. Then start SelfHostingCerberus (for this example, we use default settings, no additional command line arguments):

mono SelfHostingCerberus.exe

The server will start on the default port 1337. To leave it running and close the session, press Ctrl-B and then press 'D' (disconnect). The server will run until the hosting machine is rebooted. To reenter the tmux session, type:

tmux ls

For example:

tmux ls
Cerberus: 1 windows (created Wed Dec 19 13:03:41 2018) [80x24]

Note the terminal ID of the session ('1' - highlighted here in yellow). If there is only one background session, it is enough to type just:

tmux attach

In case there are more than one tmux sessions running, reference the terminal ID:

tmux attach -t 1

To automate starting Cerberus after system restart, please consult this sample script that should be placed under /etc/init.d. Two commands will schedule Cerberus to start after the system reboot:

sudo update-rc.d cerberus defaults
sudo update-rc.d cerberus enable

To start Cerberus manually, you would need to run this command:

sudo /etc/init.d/cerberus start