Rôle Ansible : SequenceServer

Un rôle Ansible qui installe SequenceServer sur Linux (testé avec Ubuntu 20) et déploie un serveur NCBI BLAST+ pour chaque base de données BLAST, avec les fonctionnalités suivantes :

• Les tâches BLAST sont soumises sur un cluster HPC SLURM.
• Les serveurs sont proxy inversés avec NGINX. Un accès restreint peut être configuré pour les serveurs privés, en interrogeant un serveur LDAP.
• L'interface SequenceServer peut être personnalisée de manière minimale (logo, titre, lien de support).

Exigences

L'hôte doit être configuré comme client SLURM et l'utilisateur SequenceServer doit avoir un compte SLURM pour pouvoir soumettre des tâches sur le cluster HPC SLURM. Comment installer et configurer un cluster HPC SLURM est en dehors du périmètre de ce rôle.

Les outils NCBI BLAST+ doivent être disponibles sur l'hôte et sur le cluster HPC SLURM (avec module load blast). Ils peuvent être installés avec Conda. Les bases de données BLAST doivent être formatées avec makeblastdb (voir https://sequenceserver.com/doc/#database)

Variables du rôle

Les variables disponibles sont listées ci-dessous, avec les valeurs par défaut (voir defaults/main.yml) :

# Version du gem ruby à installer (>= 2.0.0)
sequenceserver_version: 2.2.0

Variable pour définir la version de SequenceServer à installer. Ce rôle peut être utilisé avec 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']}}}]

C'est la variable utilisée pour définir les bases de données BLAST.

Pour chaque élément de la liste (chaque base de données), un serveur BLAST sera généré accessible à l'URL http://hostname/my_db (où "hostname" est le nom du serveur fourni dans l'inventaire et "name" est le nom de la base de données fournie dans la variable sequenceserver_blast_db). Chaque serveur BLAST est géré avec un service systemd appelé "sequenceserver-name.service" (configuration dans /etc/systemd/system/).

Si le serveur BLAST a besoin d'un autre reverse-proxy, il pourrait être nécessaire d'ajouter une directive pour modifier l'en-tête de réponse "location" afin d'obtenir la bonne URL pour la page de résultats (voir issue#464). Par exemple, avec un reverse-proxy apache :

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

Chaque base de données est définie comme un dictionnaire des paramètres suivants :

• name Un nom unique pour la base de données, utilisé dans l'URL
• port Un port unique inutilisé
• path Chemin absolu vers le répertoire où une ou plusieurs bases de données formatées sont situées
• users Optionnel. Utile si la base de données nécessite un accès restreint. Liste des utilisateurs autorisés (LDAP "uid").
• ldap_businesscategory Optionnel. Utile si la base de données nécessite un accès restreint. Une valeur de businessCategory LDAP. Les utilisateurs LDAP avec cette valeur "businessCategory" auront accès à la base de données.
• group Optionnel. Utile si la base de données nécessite un accès restreint. Un groupe LDAP ("gid"). Les utilisateurs LDAP qui sont membres de ce groupe auront accès à la base de données.
• web_page_title Optionnel. Le titre affiché en haut de la page web. S'il n'est pas fourni, le titre par défaut est "Serveur BLAST pour name".
• placeholders Optionnel. Une liste de dictionnaires de placeholders {key: 'key_item', value: 'value_item'} utilisés pour personnaliser le code HTML complémentaire en haut ou en bas (voir sequenceserver_top_web_page_html_path et sequenceserver_bottom_web_page_html_path). Par exemple, placeholders: [{key: 'key1', value: 'value1'}, {key: 'key2', value: 'value2'}].
• conf_options Optionnel. Une liste d'options de configuration supplémentaires pour SequenceServer en tant que dictionnaires {key: 'key_item', value: 'value_item'} (voir documentation de SequenceServer). Par exemple, [{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']}}}]

Un name et un port uniques sont obligatoires pour chaque base de données. users, ldap_businesscategory et group sont optionnels et peuvent être utilisés pour ajouter une couche d'authentification avec le module nginx-auth-ldap. Choisissez un mode d'authentification unique pour chaque base de données. Le titre du serveur BLAST peut être personnalisé avec le paramètre web_page_title. S'il n'est pas fourni, le titre par défaut est "Serveur BLAST pour name".

Les logs de SequenceServer sont stockés dans /var/log/sequenceserver/sequenceserver.log.

# Version de BLAST à utiliser dans sequenceserver (appelée avec "module load" dans le script bash slurm)
sequenceserver_blast_version: 2.14.0
# Chemin absolu vers les binaires blast
sequenceserver_blast_binaries: "~/conda3/envs/blast-{{ sequenceserver_blast_version }}/bin"
# --cpus-per-task (option SLURM)
sequenceserver_blast_threads: 4
# --mem (option SLURM)
sequenceserver_blast_mem: 16GB

Variables nécessaires pour configurer SequenceServer et les options de tâches SLURM.

# URL pour obtenir l'image du logo
sequenceserver_logo_url: ""
# Chemin local vers l'image du logo
sequenceserver_logo_path: ""
# URL vers laquelle le logo pointera
sequenceserver_home_url: "http://sequenceserver.com"
# URL vers laquelle l'icône "Aide et support" pointera
sequenceserver_support_email: "http://www.sequenceserver.com/#license-and-support"
# Chemin vers le fichier contenant le code HTML complémentaire à afficher en haut de la page web
sequenceserver_top_web_page_html_path: "~/top_web_page.html"
# Chemin vers le fichier contenant le code HTML complémentaire à afficher en bas de la page web
sequenceserver_bottom_web_page_html_path: "~/bottom_web_page.html"

Ces variables permettent de personnaliser la page web du serveur BLAST. Elles sont optionnelles. Deux variables sont disponibles pour définir le logo affiché sur le serveur BLAST : sequenceserver_logo_url ou sequenceserver_logo_path. Si les deux sont définis, le logo donné avec sequenceserver_logo_path remplacera le logo donné avec sequenceserver_logo_url. Si les fichiers sequenceserver_top_web_page_html_path ou sequenceserver_bottom_web_page_html_path existent, leur contenu sera ajouté dans le modèle RUBY de base utilisé pour afficher la page web et sera rendu en haut et en bas de la page web. Ces fichiers doivent contenir du code HTML. Cela peut être utilisé, par exemple, pour afficher des informations ou des messages d'avertissement aux utilisateurs (arrêt de service, etc.). Les placeholders définis dans la base de données paramètre placeholders (voir ci-dessus) peuvent être utilisés pour personnaliser le code HTML dans ces fichiers. Par exemple, si la base de données a le paramètre placeholders: [{key: 'key_item', value: 'value_item'}], le snippet <% if defined?(SequenceServer::Key_item) %><%= SequenceServer::Key_item %> sera remplacé par la chaîne value_item dans le code HTML rendu. Veuillez noter que la première lettre doit être en majuscule dans le snippet pour être correctement interprétée comme une constante Ruby par SequenceServer.

# Utilisateur exécutant le service sequenceserver (systemd) et exécutant les jobs blast SLURM
sequenceserver_user: "sequenceserver"

Variable pour définir l'utilisateur exécutant le service sequenceserver et soumettant les jobs SLURM. Cet utilisateur doit avoir un compte SLURM.

# Version de NGINX à installer, depuis https://nginx.org/packages/mainline
sequenceserver_nginx_version: 1.25.5
# délai d'attente de lecture proxy (directive nginx)
sequenceserver_proxy_read_timeout: 180
# Authentification avec LDAP - Obligatoire si des utilisateurs ou des groupes sont utilisés dans la variable sequenceserver_blast_db
# Sequenceserver_ldap_url: "ldap://ldap.my-domain.org/o=my-domain,c=org?uid?sub?"
sequenceserver_ldap_url: ""

Variables pour configurer le proxy inverse NGINX. sequenceserver_ldap_url doit être défini si une des bases de données a un accès restreint (utilisation des paramètres users ou group dans sequenceserver_blast_db).

Dépendances

Rôles :

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

Exemple de Playbook

- name: sequenceserver | installer le serveur blast
  hosts: blast_server
  roles:
    - abims_sbr.sequenceserver

Licence

Licence MIT

Informations sur l'auteur

Ce rôle a été créé en 2020 par Loraine Brillet-Guéguen