galaxyproject.galaxy

Galaxy

Un rôle Ansible pour installer et gérer des serveurs Galaxy. Malgré la confusion des noms, Galaxy n'a aucun lien avec Ansible Galaxy.

Vous débutez avec ce module ? Consultez notre tutoriel

Exigences

Ce rôle a les mêmes dépendances que le module git. De plus, pip et Python virtualenv sont requis. Ceux-ci peuvent être installés facilement via une pré-tâche dans le même jeu de tâches que ce rôle :

- hosts: galaxyservers
  pre_tasks:
    - name: Installer les dépendances
      apt:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'Debian'
      with_items:
        - git
        - python-pip
        - python-virtualenv
    - name: Installer les dépendances
      yum:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'RedHat'
      with_items:
        - git
        - python-virtualenv
  roles:
    - galaxyproject.galaxy

Si votre exécutable git n'est pas dans $PATH, vous pouvez spécifier son emplacement avec la variable git_executable. De même pour l'exécutable virtualenv avec la variable correspondante galaxy_virtualenv_command.

Variables de rôle

Toutes les variables ne sont pas listées ou expliquées en détail. Pour plus d'informations sur les variables moins couramment utilisées, consultez le fichier des valeurs par défaut.

De nombreuses variables contrôlent où des fichiers spécifiques sont placés et où Galaxy écrit des données. Afin de simplifier la configuration, vous pouvez sélectionner une configuration avec la variable galaxy_layout. Le choix de la configuration affecte les variables requises.

Variables requises

Si vous utilisez une configuration autre que root-dir :

galaxy_server_dir: Chemin du système de fichiers où le code du serveur Galaxy sera installé (cloné).

Si vous utilisez root-dir :

galaxy_root: Chemin du système de fichiers à la racine d'un déploiement Galaxy, le code du serveur Galaxy sera installé dans un sous-répertoire de ce répertoire.

Variables optionnelles

L'option galaxy_config_perms contrôle les permissions des fichiers de configuration de Galaxy. Cette option a été ajoutée dans la version 0.9.18 du rôle et la valeur par défaut est 0640 (lecture et écriture pour l'utilisateur, lecture seule pour le groupe, les autres utilisateurs n'ont pas de permissions). Dans les anciennes versions, le rôle ne contrôlait pas les permissions des fichiers de configuration, donc soyez conscient que les permissions de vos fichiers de configuration peuvent changer à partir de 0.9.18 et plus tard.

Contrôle de la configuration

galaxy_layout: les mises en page disponibles peuvent être trouvées dans le sous-répertoire vars/ et les valeurs possibles incluent :
- root-dir: Tout est organisé dans des sous-répertoires sous un seul répertoire racine.
- opt: Une mise en page conforme à FHS répartie sur plusieurs répertoires comme /opt, /etc/opt, etc.
- legacy-improved: Tout est sous le répertoire du serveur Galaxy, comme avec run.sh.
- legacy: La mise en page par défaut avant l'existence de galaxy_layout et actuellement la valeur par défaut afin de ne pas casser l'utilisation existante de ce rôle.
- custom: Valeurs par défaut raisonnables pour des configurations personnalisées, nécessite la définition de quelques variables comme décrit dans vars/layout-custom.yml

Les configurations root-dir ou opt sont recommandées pour de nouveaux déploiements Galaxy.

Les options ci-dessous permettant de contrôler le placement des fichiers ou sous-répertoires peuvent encore remplacer les valeurs par défaut définies par la configuration.

Contrôle de processus avec Gravity

Le rôle peut gérer le service Galaxy en utilisant gravity. Cela est la valeur par défaut pour Galaxy 22.05 et ultérieur. De plus, le support pour la variable galaxy_restart_handler_name a été supprimé. Si vous devez activer votre propre gestionnaire de redémarrage personnalisé, vous pouvez utiliser l'option "listen" au gestionnaire comme expliqué dans la documentation des gestionnaires. Le gestionnaire doit "écouter" le sujet "restart galaxy".

Thèmes Galaxy

Depuis la version 22.01, les utilisateurs de Galaxy peuvent choisir entre différents thèmes. Vous pouvez définir des thèmes en utilisant la variable galaxy_themes, la syntaxe étant identique à celle du fichier themes_conf.yml décrit dans la formation sur les thèmes.

La variable galaxy_manage_themes contrôle si le rôle gère les configurations de thèmes et est activée automatiquement si galaxy_themes est défini. Si vous souhaitez simplement charger les thèmes d'exemple de themes_conf.yml.sample sans définir votre propre, vous pouvez définir manuellement galaxy_manage_themes sur true.

Sous-domaines Galaxy

Depuis la version 22.01, Galaxy peut servir différents contenus statiques et thèmes par hôte (par exemple, sous-domaine).

En définissant galaxy_manage_subdomain_static: yes, vous activez la création de répertoires statiques et de configurations par hôte.

Pour utiliser cette fonctionnalité, vous devez créer la structure de répertoires suivante sous files/ (personnalisable avec la variable galaxy_themes_ansible_file_path):

files/galaxy/static
├──<nom-sous-domaine-1>
│   └── static
│       ├── dist (optionnel)
│       │   └── some-image.png
│       ├── images (optionnel)
│       │   └── more-content.jpg
│       └── welcome.html (optionnel, galaxyproject.org sera affiché sinon.)
├── <nom-sous-domaine-2>                            
│   └── static
│       ├── dist (optionnel)
│       │   ├── another-static-image.svg
│       │   └── more-static-content-2.svg
│       └── welcome.html (optionnel)
... (et bien d'autres sous-domaines)

Où <nom-sous-domaine-1> doit correspondre exactement au nom de votre sous-domaine. Le sous-répertoire static est obligatoire, tandis que tous les sous-répertoires dans static sont optionnels. Les sous-répertoires et fichiers copiés sont gérés par la variable static_galaxy_themes_keys.

Assurez-vous également de définir galaxy_themes_welcome_url_prefix, afin que vos pages d'accueil soient correctement template.

Il est impératif de définir les variables sous galaxy_themes_subdomains comme indiqué dans l'exemple dans defaults/main.yml. Si vous avez activé la variable galaxy_manage_host_filters, vous pouvez également spécifier les sections d'outils qui doivent être affichées pour chaque sous-domaine individuel.

Chaque sous-domaine peut avoir son propre thème, qui est défini sous la clé theme de l'entrée du sous-domaine dans galaxy_themes_subdomains. Ce thème sera le par défaut pour le sous-domaine, et tout autre thème défini globalement pour le serveur sera également disponible pour l'utilisateur. Si le theme d'un sous-domaine n'est pas défini, la valeur par défaut globale est utilisée. Un exemple est fourni dans defaults/main.yml.

Contrôle des fonctionnalités

Plusieurs variables contrôlent quelles fonctions ce rôle exécutera (toutes par défaut oui sauf indication contraire) :

galaxy_create_user (par défaut: non): Créer l'utilisateur Galaxy. Travailler sous un utilisateur dédié est une bonne pratique, mais la plupart des instances Galaxy en production soumettant des tâches à un cluster géreront les utilisateurs dans un service d'annuaire (ex. LDAP). Cette option est utile pour les serveurs autonomes. Nécessite des privilèges super utilisateur.
galaxy_manage_paths (par défaut: non): Créer et gérer la propriété/permissions des chemins Galaxy configurés. Nécessite des privilèges super utilisateur.
galaxy_manage_clone: Cloner Galaxy depuis le dépôt source et le maintenir à une version spécifique (commit), ainsi que mettre en place un [virtualenv][virtualenv] à partir duquel il peut être exécuté.
galaxy_manage_download: Télécharger et décompresser Galaxy à partir d'une archive distante, ainsi que mettre en place un [virtualenv][virtualenv] à partir duquel il peut être exécuté.
galaxy_manage_existing: Prendre en charge un répertoire Galaxy déjà existant, ainsi que mettre en place un [virtualenv][virtualenv] à partir duquel il peut être exécuté. galaxy_server_dir doit pointer vers le chemin qui contient déjà le code source de Galaxy.
galaxy_manage_static_setup: Gérer les fichiers de configuration "statique" de Galaxy - ceux qui ne peuvent pas être modifiés par le serveur Galaxy lui-même. Au minimum, cela comprend le fichier de configuration principal de Galaxy, galaxy.ini.
galaxy_manage_mutable_setup: Gérer les fichiers de configuration "mutable" de Galaxy - ceux qui peuvent être modifiés par Galaxy (ex. lors de l'installation d'outils depuis le Galaxy Tool Shed).
galaxy_manage_database: Mettre à niveau le schéma de la base de données si nécessaire, lorsque de nouvelles versions de schéma deviennent disponibles.
galaxy_fetch_dependencies: Récupérer les modules dépendants de Galaxy dans le virtualenv de Galaxy.
galaxy_build_client: Construire l'application client de Galaxy (interface utilisateur web).
galaxy_client_make_target (par défaut: client-production-maps): Définir le type de construction du client. Les options incluent : client, client-production et client-production-maps. Voir README du client Galaxy pour plus de détails.
galaxy_manage_systemd (par défaut: non): Installer une unité de service systemd pour démarrer et arrêter Galaxy avec le système (en utilisant la commande systemctl).
galaxy_manage_errordocs (par défaut: non): Installer des documents d'erreur HTTP 413 et 502 style Galaxy pour nginx. Nécessite des privilèges d'écriture pour le répertoire des documents d'erreur de nginx.
galaxy_manage_cleanup (par défaut: non): Installer une tâche cron pour nettoyer le cadre Galaxy et les fichiers temporaires d'exécution des jobs. Nécessite tmpwatch(8) sur les systèmes basés sur RedHat ou tmpreaper(8) sur les systèmes basés sur Debian. Voir les variables galaxy_tmpclean_* dans le fichier des valeurs par défaut pour plus de détails.

Code et configuration de Galaxy

Options pour configurer Galaxy et contrôler quelle version est installée.

galaxy_config: Le contenu du fichier de configuration Galaxy (galaxy.ini par défaut) est contrôlé par cette variable. C'est une structure de données (hash de hash) qui sera traduite dans le fichier de configuration. Voir les exemples de jeux de tâches ci-dessous pour utilisation.
galaxy_config_files: Liste de structures de données (avec des clés src et dest) de fichiers à copier depuis la machine de contrôle. Par exemple, pour définir les destinations des jobs, vous pouvez utiliser la variable galaxy_config_dir suivie du nom de fichier comme dest, par ex. dest: "{{ galaxy_config_dir }}/job_conf.xml". Assurez-vous d'ajouter la configuration appropriée dans galaxy_config pour chaque fichier ajouté ici (donc, si vous ajoutez job_conf.xml, assurez-vous que galaxy_config.galaxy.job_config_file pointe vers ce fichier).
galaxy_config_templates: Liste de structures de données (avec des clés src et dest) de modèles à remplir depuis la machine de contrôle.
galaxy_local_tools: Liste de fichiers ou répertoires d'outils locaux à copier depuis la machine de contrôle, par rapport à galaxy_local_tools_src_dir (par défaut : files/galaxy/tools dans le jeu de tâches). Les éléments de la liste peuvent être soit un nom de fichier d'outil, soit une structure de données avec les clés file, section_name et, éventuellement, section_id. Si aucun section_name n'est spécifié, les outils seront placés dans une section nommée Outils locaux.
galaxy_local_tools_dir: Répertoire sur le serveur Galaxy où les outils locaux seront installés.
galaxy_dynamic_job_rules: Liste de règles de jobs dynamiques à copier depuis la machine de contrôle, par rapport à galaxy_dynamic_job_rules_src_dir (par défaut : files/galaxy/dynamic_job_rules dans le jeu de tâches).
galaxy_dynamic_job_rules_dir (par défaut : {{ galaxy_server_dir }}/lib/galaxy/jobs/rules): Répertoire sur le serveur Galaxy où les règles de jobs dynamiques seront installées. Si modifié par rapport au défaut, assurez-vous que le répertoire est sur le $PYTHONPATH de Galaxy (par ex. dans {{ galaxy_venv_dir }}/lib/python2.7/site-packages) et configurez le plugin de règles dynamiques dans job_conf.xml en conséquence.
galaxy_repo (par défaut : https://github.com/galaxyproject/galaxy.git): Dépôt Git en amont à partir duquel Galaxy doit être cloné.
galaxy_commit_id (par défaut : master): Un identifiant de commit, étiquette, branche ou autre référence Git valide à laquelle Galaxy doit être mis à jour. Spécifier une branche mettra à jour vers le dernier commit sur cette branche. Utiliser un véritable identifiant de commit est le seul moyen de verrouiller explicitement Galaxy à une version spécifique.
galaxy_force_checkout (par défaut : non): Si oui, tous les fichiers modifiés dans le dépôt Galaxy seront supprimés.
galaxy_clone_depth (par défaut : non défini): Profondeur à utiliser lors de l'exécution git clone. Laissez non spécifié pour cloner tout l'historique.

Fichiers de configuration supplémentaires

Certains fichiers de configuration optionnels couramment utilisés dans les serveurs Galaxy de production peuvent être configurés via des variables :

galaxy_dependency_resolvers: Remplir le fichier dependency_resolvers_conf.yml. Voir la configuration XML d'exemple pour les options.
galaxy_container_resolvers: Remplir le fichier container_resolvers_conf.yml. Voir la configuration XML d'exemple pour les options.
galaxy_job_metrics_plugins: Remplir le fichier job_metrics_conf.yml. Voir la configuration XML d'exemple pour les options.

Depuis Galaxy 21.05, les fichiers de configuration d'exemple pour ces caractéristiques sont en XML, mais YAML est également pris en charge comme suit :

galaxy_dependency_resolvers:
  - type: <nom de l'élément XML>
    <nom de l'attribut XML>: <valeur de l'attribut XML>

Par exemple :

galaxy_dependency_resolvers:
  - type: galaxy_packages
  - type: conda
    prefix: /srv/galaxy/conda
    auto_init: true
    auto_install: false

Configuration des chemins

Options pour contrôler où certains composants de Galaxy sont placés sur le système de fichiers.

galaxy_venv_dir (par défaut : <galaxy_server_dir>/.venv): Le rôle créera un [virtualenv][virtualenv] à partir duquel Galaxy fonctionnera, cela contrôle où le virtualenv sera placé.
galaxy_virtualenv_command: (par défaut : virtualenv): La commande utilisée pour créer le virtualenv de Galaxy. Définissez sur pyvenv pour utiliser Python 3 sur Galaxy >= 20.01.
galaxy_virtualenv_python: (par défaut : python de la première commande virtualenv ou python dans $PATH): Le binaire python à utiliser lors de la création du virtualenv. Pour Galaxy < 20.01, utilisez python2.7 (si ce n'est pas le défaut), pour Galaxy >= 20.01, utilisez python3.5 ou plus.
galaxy_config_dir (par défaut : <galaxy_server_dir>): Répertoire utilisé pour les fichiers de configuration "statistiques".
galaxy_mutable_config_dir (par défaut : <galaxy_server_dir>): Répertoire utilisé pour les fichiers de configuration "mutables", doit être accessible en écriture par l'utilisateur exécutant Galaxy.
galaxy_mutable_data_dir (par défaut : <galaxy_server_dir>/database): Répertoire utilisé pour les données "mutables" et les caches, doit être accessible en écriture par l'utilisateur exécutant Galaxy.
galaxy_config_file (par défaut : <galaxy_config_dir>/galaxy.ini): Fichier de configuration principal de Galaxy.

Gestion des utilisateurs et séparation des privilèges

galaxy_separate_privileges (par défaut: non): Activer le mode de séparation des privilèges.
galaxy_user (par défaut : utilisateur exécutant Ansible): Le nom de l'utilisateur système sous lequel Galaxy fonctionne.
galaxy_privsep_user (par défaut : root): Le nom de l'utilisateur système qui possède le code Galaxy, les fichiers de configuration et le virtualenv (et les dépendances associées).
galaxy_group: Groupe commun entre l'utilisateur Galaxy et l'utilisateur de séparation de privilèges. S'il est défini et que galaxy_manage_paths est activé, les répertoires contenant des informations sensibles, telles que le fichier de configuration de Galaxy, seront créés avec des permissions de groupe mais non accessibles au public. Sinon, les répertoires seront accessibles au public.

Contrôle de la méthode d'accès

Le rôle doit effectuer des tâches en tant qu'utilisateurs différents selon les fonctionnalités que vous avez activées et la façon dont vous vous connectez à l'hôte cible. Par défaut, le rôle utilisera become (c'est-à-dire sudo) pour effectuer des tâches en tant qu'utilisateur approprié si cela est jugé nécessaire. Remplacer ce comportement est discuté dans le fichier des valeurs par défaut.

systemd

systemd est le démon d'initialisation standard sur la plupart des distributions Linux modernes (et toutes celles prises en charge par ce rôle). Si galaxy_manage_systemd est activé, un service galaxy sera configuré dans systemd pour exécuter Galaxy. Ce service sera automatiquement démarré et configuré pour démarrer lors du démarrage de votre système. Vous pouvez contrôler le service Galaxy avec l'utilitaire systemctl en tant qu'utilisateur root ou avec sudo:

# systemctl start galaxy     # démarrer galaxy
# systemctl reload galaxy    # tenter un "rechargement cordial"
# systemctl restart galaxy   # effectuer un redémarrage complet
# systemctl stop galaxy      # arrêter galaxy

Vous pouvez utiliser le mode utilisateur de systemd si vous n'avez pas de privilèges root sur votre système en définissant galaxy_systemd_root sur false. Ajoutez --user aux commandes systemctl ci-dessus pour interagir avec systemd en mode utilisateur :

Documents d'erreur

galaxy_errordocs_dir: Installer des documents d'erreur HTTP 413 et 502 style Galaxy dans ce répertoire. Le message 502 utilise les inclusions côté serveur de nginx pour permettre aux administrateurs de créer un message personnalisé dans ~/maint lorsque Galaxy est en panne. nginx doit être configuré séparément pour servir ces documents d'erreur.
galaxy_errordocs_server_name (par défaut : Galaxy): utilisé pour afficher le message "galaxy_errdocs_server_name ne peut pas être atteint" sur la page 502.
galaxy_errordocs_prefix (par défaut : /error): Chemin côté web vers la racine des documents d'erreur.

Options diverses

galaxy_admin_email_to: Si défini, envoyer un email à cette adresse lorsque Galaxy a été mis à jour. Suppose que le mail est correctement configuré sur l'hôte géré.
galaxy_admin_email_from: Adresse à partir de laquelle envoyer l'email ci-dessus.

Dépendances

Aucune

Exemple de jeu de tâches

Basique

Installer Galaxy sur votre système local avec toutes les options par défaut :

- hosts: localhost
  vars:
    galaxy_server_dir: /srv/galaxy
  connection: local
  roles:
     - galaxyproject.galaxy

Si votre version d'Ansible >= 2.10.4, lorsque vous exécutez ansible-playbook playbook.yml, vous devez fournir un argument supplémentaire -u $USER, sinon vous obtiendrez une erreur.

Une fois installé, vous pouvez commencer par :

$ cd /srv/galaxy
$ sh run.sh

Meilleures pratiques

Installer Galaxy selon les pratiques recommandées pour les serveurs de production actuels :

Le code Galaxy (clone) est "propre" : aucune configuration ou donnée mutable ne vit sous le clone
Le code Galaxy et les configurations statiques sont séparés par privilèges : non possédés / modifiables par l'utilisateur qui exécute Galaxy
Les fichiers de configuration ne sont pas lisibles par le public
PostgreSQL est utilisé comme base de données
Le style de configuration YAML 18.01+ est utilisé
Deux gestionnaires de tâches sont démarrés
Lorsque le code ou les configs de Galaxy sont mis à jour par Ansible, Galaxy sera redémarré en utilisant galaxyctl ou systemctl restart galaxy-*

- hosts: galaxyservers
  vars:
    galaxy_config_style: yaml
    galaxy_layout: root-dir
    galaxy_root: /srv/galaxy
    galaxy_commit_id: release_23.0
    galaxy_separate_privileges: yes
    galaxy_force_checkout: true
    galaxy_create_user: yes
    galaxy_manage_paths: yes
    galaxy_manage_systemd: yes
    galaxy_user: galaxy
    galaxy_privsep_user: gxpriv
    galaxy_group: galaxy
    postgresql_objects_users:
      - name: galaxy
        password: null
    postgresql_objects_databases:
      - name: galaxy
        owner: galaxy
    galaxy_config:
      gravity:
        process_manager: systemd
        galaxy_root: "{{ galaxy_root }}/server"
        galaxy_user: "{{ galaxy_user_name }}"
        virtualenv: "{{ galaxy_venv_dir }}"
        gunicorn:
          # options d'écoute
          bind: "unix:{{ galaxy_mutable_config_dir }}/gunicorn.sock"
          # options de performance
          workers: 2
          # Autres options qui seront passées à gunicorn
          # Cela permet de définir des en-têtes 'secure' comme REMOTE_USER (et d'autres)
          # https://docs.gunicorn.org/en/stable/settings.html#forwarded-allow-ips
          extra_args: '--forwarded-allow-ips="*"'
          # Cela permet à Gunicorn de démarrer Galaxy complètement avant de fork, ce qui est plus rapide.
          # https://docs.gunicorn.org/en/stable/settings.html#preload-app
          preload: true
        celery:
          concurrency: 2
          enable_beat: true
          enable: true
          queues: celery,galaxy.internal,galaxy.external
          pool: threads
          memory_limit: 2
          loglevel: DEBUG
        handlers:
          handler:
            processes: 2
            pools:
              - job-handlers
              - workflow-schedulers
      galaxy:
        database_connection: "postgresql:///galaxy?host=/var/run/postgresql"
  pre_tasks:
    - name: Installer les dépendances
      apt:
        name:
          - sudo
          - git
          - make
          - python3-venv
          - python3-setuptools
          - python3-dev
          - python3-psycopg2
          - gcc
          - acl
          - gnutls-bin
          - libmagic-dev
      become: yes
  roles:
    # Installer avec :
    #   % ansible-galaxy install galaxyproject.postgresql
    - role: galaxyproject.postgresql
      become: yes
    # Installer avec :
    #   % ansible-galaxy install natefoo.postgresql_objects
    - role: galaxyproject.postgresql_objects
      become: yes
      become_user: postgres
    - role: galaxyproject.galaxy