Ansible Role: SequenceServer

This is an Ansible Role that sets up SequenceServer on a Linux system (tested with Ubuntu 20). It also deploys an NCBI BLAST+ server for each BLAST database. Key features include:

• BLAST jobs are sent to a SLURM HPC cluster.
• The server is accessed through NGINX, with options to restrict access using an LDAP server.
• You can customize the SequenceServer interface minimally (like logo, title, support link).

Requirements

Your system needs to be set up as a SLURM client, and the SequenceServer user must have a SLURM account to submit jobs. Instructions for setting up a SLURM HPC cluster are not included here.

The NCBI BLAST+ tools must be available both on your machine and the SLURM HPC cluster (you can load them using module load blast). They can be installed using Conda. You need to format BLAST databases with makeblastdb (see https://sequenceserver.com/doc/#database).

Role Variables

Here are some available variables and their default values (see defaults/main.yml):

# Version of the ruby gem to install (>= 2.0.0)
sequenceserver_version: 2.2.0

This variable sets the version of SequenceServer to install. The role works with SequenceServer version >= 2.0.0.

sequenceserver_blast_db:
    - name: 'my_db'
      port: '4567'
      path: '/path/to/my/db'
      users: ['fbar','jsmith']
      web_page_title: 'blablabla'
      placeholders: [{key: 'key1', value: 'value1'}, {key: 'key2', value: 'value2'}]
      conf_options: [{key: 'job_lifetime', value: '10080'}, {key: 'databases_widget', value: 'tree'}, {key: 'options', value: {'blastn': {'default': ['-task blastn', '-evalue 1e-5'], 'short-seq': ['-task blastn-short', '-evalue 1e-1']}}}]

This variable defines the BLAST databases.

For each database entry, a BLAST server will be created accessible at http://hostname/my_db (where "hostname" is the server name from the inventory, and "my_db" is the name you set). Each server is managed by a systemd service called "sequenceserver-name.service" (configuration in /etc/systemd/system/).

If you need a different reverse-proxy setup, you may need to adjust a directive to modify the response header "location" for the correct URL on the results page (see issue#464). For example, with an Apache reverse-proxy:

<LocationMatch "^/(?<instance>[^/]+)/">
   Header edit Location "(^http[s]?://)([a-zA-Z0-9\.\-]+)(:\d+)?/(%{MATCH_INSTANCE}e/)?" "/%{MATCH_INSTANCE}e/" env=MATCH_INSTANCE
</LocationMatch>

Each database entry must have:

• name: A unique name for the database, used in the URL.
• port: An available port number.
• path: The absolute path to the directory where the formatted databases are stored.
• users: Optional. A list of authorized users if access is restricted.
• ldap_businesscategory: Optional. Used for restricted access based on LDAP users' categories.
• group: Optional. An LDAP group for access control.
• web_page_title: Optional. The title display at the top of the webpage, defaults to "BLAST server for name".
• placeholders: Optional. For customizing HTML code (top or bottom) displayed on the webpage.
• conf_options: Optional. Additional configuration options for SequenceServer.

The name and port are required for each database. users, ldap_businesscategory, and group are optional for added authentication. Only one authentication method should be chosen for each database. The server title can be customized with the web_page_title parameter.

SequenceServer logs are found in /var/log/sequenceserver/sequenceserver.log.

# Version of BLAST to use in sequenceserver
sequenceserver_blast_version: 2.14.0
# Absolute path to the blast binaries
sequenceserver_blast_binaries: "~/conda3/envs/blast-{{ sequenceserver_blast_version }}/bin"
# SLURM option for CPUs per task
sequenceserver_blast_threads: 4
# SLURM option for memory
sequenceserver_blast_mem: 16GB

These variables are necessary for configuring SequenceServer and SLURM job options.

# URL for the logo image
sequenceserver_logo_url: ""
# Local file path for the logo image
sequenceserver_logo_path: ""
# URL the logo links to
sequenceserver_home_url: "http://sequenceserver.com"
# URL for the 'Help and support' icon
sequenceserver_support_email: "http://www.sequenceserver.com/#license-and-support"
# Path for supplementary HTML code at the top of the page
sequenceserver_top_web_page_html_path: "~/top_web_page.html"
# Path for supplementary HTML code at the bottom of the page
sequenceserver_bottom_web_page_html_path: "~/bottom_web_page.html"

These variables allow webpage customization. You can set the logo using sequenceserver_logo_url or sequenceserver_logo_path. If both are set, the sequenceserver_logo_path takes priority. If sequenceserver_top_web_page_html_path or sequenceserver_bottom_web_page_html_path are specified, their content will be included in the displayed webpage, which can be used for messages to users (service announcements, etc.). The placeholders from the placeholders parameter can also be used in these files for dynamic content.

# User for sequenceserver service (systemd) and SLURM jobs
sequenceserver_user: "sequenceserver"

This variable sets the user for running the sequenceserver service and submitting SLURM jobs. This user must have a SLURM account.

# NGINX version to install
sequenceserver_nginx_version: 1.25.5
# NGINX proxy read timeout
sequenceserver_proxy_read_timeout: 180
# LDAP authentication (mandatory for restricted access databases)
sequenceserver_ldap_url: ""

These variables configure the NGINX reverse-proxy. sequenceserver_ldap_url should be set if a database requires restricted access (using users or group).

Dependencies

Roles needed:

• nginxinc.nginx
• geerlingguy.git
• geerlingguy.ruby

Example Playbook

- name: sequenceserver | install blast server
  hosts: blast_server
  roles:
    - abims_sbr.sequenceserver

License

MIT License

Author Information

This role was created in 2020 by Loraine Brillet-Guéguen