galaxyproject.galaxy

ギャラクシー

Galaxyサーバーをインストールして管理するためのAnsibleロールです。名前が似ていますが、GalaxyとAnsible Galaxyには関係がありません。

このモジュールの使い方を知りたいですか？こちらのTutorialをチェックしてください。

要件

このロールはgitモジュールと同じ依存関係を持ちます。さらに、pipとPython仮想環境が必要です。これらは同じプレイでプリタスクを使って簡単にインストールできます。

- hosts: galaxyservers
  pre_tasks:
    - name: 依存関係のインストール
      apt:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'Debian'
      with_items:
        - git
        - python-pip
        - python-virtualenv
    - name: 依存関係のインストール
      yum:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'RedHat'
      with_items:
        - git
        - python-virtualenv
  roles:
    - galaxyproject.galaxy

git実行可能ファイルが$PATHにない場合は、git_executable変数でその場所を指定できます。virtualenv実行可能ファイルについても同様にgalaxy_virtualenv_command変数を使って指定できます。

ロール変数

すべての変数がリストされているわけではありません。あまり使われない変数についての詳細は、defaults fileをご覧ください。

多くの変数は特定のファイルがどこに置かれるかや、Galaxyがデータを書き込む場所を制御します。設定を簡略化するために、galaxy_layout変数でレイアウトを選択できます。選択するレイアウトによって必要な変数が変わります。

必要な変数

root-dir以外のレイアウトを使用する場合：

galaxy_server_dir: Galaxyサーバーコードがインストール（クローン）されるファイルシステムのパス。

root-dirを使用する場合：

galaxy_root: Galaxy展開のルートのファイルシステムパス。Galaxyサーバーコードはこのディレクトリのサブディレクトリにインストールされます。

オプションの変数

galaxy_config_permsオプションは、Galaxyの設定ファイルのパーミッションを制御します。このオプションはこのロールのバージョン0.9.18で追加され、デフォルト値は0640（ユーザーの読み書き、グループの読み取りのみ、その他のユーザーに対するパーミッションなし）です。古いバージョンでは、ロールが設定ファイルのパーミッションを制御していなかったため、0.9.18以降に設定ファイルのパーミッションが変更される可能性があることに注意してください。

レイアウト制御

galaxy_layout: 使用可能なレイアウトは、vars/サブディレクトリにあり、可能な値には以下が含まれます：
- root-dir: すべてが単一のルートディレクトリの下に配置されます。
- opt: /opt、/etc/optなどの複数のディレクトリにわたるFHS準拠のレイアウト。
- legacy-improved: Galaxyサーバーディレクトリの下にすべて、run.shのように。
- legacy: galaxy_layoutが存在する前のデフォルトレイアウトで、現在は既存のこのロールの使用を壊さないようにデフォルトです。
- custom: カスタムレイアウトのための合理的なデフォルト、vars/layout-custom.ymlで説明されている数個の変数を設定する必要があります。

新しいGalaxyの展開にはroot-dirまたはoptレイアウトがお勧めです。

個々のファイルまたはサブディレクトリの配置を制御するオプションはまだレイアウトによって設定されたデフォルトを上書きできます。

重力によるプロセス制御

ロールはgravityを使用してGalaxyサービスを管理できます。これはGalaxy 22.05以降のデフォルトです。さらに、galaxy_restart_handler_name変数のサポートが削除されました。独自のカスタム再起動ハンドラを有効にする必要がある場合は、ハンドラのドキュメントで説明されているように"listen"オプションを使用できます。ハンドラは"restart galaxy"というトピックを「聞く」必要があります。

Galaxyテーマ

22.01以降、Galaxyユーザーは異なるUIテーマを選択できます。galaxy_themes変数を使用してテーマを定義することができ、その構文はthemes trainingで説明されているthemes_conf.ymlファイルと同じです。

galaxy_manage_themes変数は、ロールがテーマ設定を管理するかどうかを制御し、galaxy_themesが定義されている場合は自動的に有効になります。独自のテーマを定義せずにGalaxyのthemes_conf.yml.sampleからサンプルテーマを読み込みたいだけの場合は、galaxy_manage_themesをtrueに手動で設定できます。

Galaxyサブドメイン

22.01以降、Galaxyはホストごとに異なる静的コンテンツやテーマを提供できます（例：サブドメイン）。

galaxy_manage_subdomain_static: yesを設定すると、ホストごとに静的ディレクトリと設定の作成が有効になります。

この機能を使用するには、以下のディレクトリ構造をfiles/の下に作成する必要があります（galaxy_themes_ansible_file_path変数でカスタマイズ可能）：

files/galaxy/static
├──<subdomain-name-1>
│   └── static
│       ├── dist (オプション)
│       │   └── some-image.png
│       ├── images (オプション)
│       │   └── more-content.jpg
│       └── welcome.html (オプション、そうでない場合はgalaxyproject.orgが表示されます)
├── <subdomain-name-2>                            
│   └── static
│       ├── dist (オプション)
│       │   ├── another-static-image.svg
│       │   └── more-static-content-2.svg
│       └── welcome.html (オプション)
... (他にも多くのサブドメイン)

ここで、<subdomain-name-1>はサブドメインの名前と正確に一致する必要があります。サブディレクトリstaticは必須で、static内のサブディレクトリはすべてオプションです。どのサブディレクトリやファイルがコピーされるかは、static_galaxy_themes_keys変数によって管理されます。

また、galaxy_themes_welcome_url_prefixを設定して、ウェルカムページが正しくテンプレート化されるようにしてください。

galaxy_themes_subdomainsの変数は、defaults/main.ymlに示されている例に従って設定する必要があります。galaxy_manage_host_filters変数を有効にした場合は、各サブドメインに表示するツールセクションも指定できます。

各サブドメインには独自のテーマを持たせることができ、これはgalaxy_themes_subdomainsのサブドメインエントリのthemeキーで定義されます。このテーマはサブドメインのデフォルトとなり、サーバーでグローバルに定義されている他のテーマもユーザーが選択できるようになります。サブドメインのthemeが定義されていない場合は、グローバルデフォルトが使用されます。defaults/main.ymlに例があります。

機能制御

いくつかの変数は、このロールが実行する機能を制御します（すべてデフォルトはyesですが、特に記載がない場合を除く）。

galaxy_create_user（デフォルト: no）：Galaxyユーザーを作成します。専用ユーザーで実行するのはベストプラクティスですが、クラスターにジョブを送信するほとんどの本番Galaxyインスタンスはディレクトリサービス（例：LDAP）でユーザーを管理します。このオプションはスタンドアロンサーバーに便利です。スーパーユーザー特権が必要です。
galaxy_manage_paths（デフォルト: no）：設定されたGalaxyパスの所有権とパーミッションを作成および管理します。スーパーユーザー特権が必要です。
galaxy_manage_clone：Galaxyをソースリポジトリからクローンし、指定されたバージョン（コミット）に保ち、実行できる[virtualenv][virtualenv]のセットアップを行います。
galaxy_manage_download：リモートアーカイブURLからGalaxyをダウンロードおよび展開し、実行できる[virtualenv][virtualenv]のセットアップを行います。
galaxy_manage_existing：既に存在するGalaxyディレクトリを管理し、実行できる[virtualenv][virtualenv]のセットアップを行います。galaxy_server_dirは、既にGalaxyのソースコードが含まれるパスを指さなければなりません。
galaxy_manage_static_setup：Galaxyの「静的」設定ファイルを管理します。これには、主要なGalaxy設定ファイルであるgalaxy.iniが含まれます。
galaxy_manage_mutable_setup：Galaxyによって変更可能な「可変」設定ファイルを管理します（例：Galaxy Tool Shedからツールをインストールする際）。
galaxy_manage_database：新しいスキーマバージョンが利用可能になると、必要に応じてデータベーススキーマをアップグレードします。
galaxy_fetch_dependencies：Galaxy依存モジュールをGalaxyのvirtualenvに取得します。
galaxy_build_client：Galaxyクライアントアプリケーション（ウェブUI）をビルドします。
galaxy_client_make_target（デフォルト: client-production-maps）：クライアントビルドの種類を設定します。オプションにはclient、client-production、client-production-mapsがあります。Galaxyクライアントリードミーに詳細があります。
galaxy_manage_systemd（デフォルト: no）：Galaxyをシステムで起動および停止するためのsystemdサービスユニットをインストールします（systemctlコマンドを使用）。
galaxy_manage_errordocs（デフォルト: no）：nginx用のGalaxyスタイルの413および502 HTTPエラー文書をインストールします。nginxエラードキュメントディレクトリへの書き込み権限が必要です。
galaxy_manage_cleanup（デフォルト: no）：Galaxyフレームワークとジョブ実行の一時ファイルをクリーンアップするためのcronジョブをインストールします。RedHat系システムではtmpwatch(8)、Debian系システムではtmpreaper(8)が必要です。defaults fileのgalaxy_tmpclean_*変数に詳しい情報があります。

Galaxyのコードと設定

Galaxyを構成し、どのバージョンがインストールされるかを制御するためのオプション。

galaxy_config: Galaxy設定ファイル（デフォルトはgalaxy.ini）の内容はこの変数で制御されます。これはハッシュのハッシュ（または辞書）であり、設定ファイルに変換されます。使用例は以下のExample Playbooksをご覧ください。
galaxy_config_files: 管理対象マシンからコピーするファイルのハッシュ（srcとdestキーを持つリスト）。例えば、ジョブの宛先を設定するには、galaxy_config_dir変数の後にファイル名をdestとして使用できます（例：dest: "{{ galaxy_config_dir }}/job_conf.xml"）。ここで追加される各ファイルに対して適切な設定をgalaxy_config内に追加してください（job_conf.xmlを追加する場合は、galaxy_config.galaxy.job_config_fileがそのファイルを指すようにします）。
galaxy_config_templates: 管理対象マシンからコピーするテンプレートのハッシュ（srcとdestキーを持つリスト）。
galaxy_local_tools: 管理対象マシンから、galaxy_local_tools_src_dirに相対的なローカルツールファイルまたはディレクトリのリスト（デフォルトはプレイブック内のfiles/galaxy/tools）。リスト項目はツールファイル名でも良いし、またはfile、section_name、およびオプションでsection_idキーを持つ辞書でも構いません。section_nameが指定されていない場合、ツールはローカルツールというセクションに配置されます。
galaxy_local_tools_dir: Galaxyサーバー上でローカルツールがインストールされるディレクトリ。
galaxy_dynamic_job_rules: 管理対象マシンからコピーする動的ジョブルールのリスト、galaxy_dynamic_job_rules_src_dirに相対的（デフォルトはプレイブック内のfiles/galaxy/dynamic_job_rules）。
galaxy_dynamic_job_rules_dir（デフォルト: {{ galaxy_server_dir }}/lib/galaxy/jobs/rules）：動的ジョブルールがインストールされるGalaxyサーバー上のディレクトリ。デフォルトから変更があった場合、ディレクトリがGalaxyの$PYTHONPATHにあることを確認してください（例：{{ galaxy_venv_dir }}/lib/python2.7/site-packages）し、job_conf.xmlで動的ルールプラグインを適切に設定してください。
galaxy_repo（デフォルト: https://github.com/galaxyproject/galaxy.git）：Galaxyがクローンされる上流のGitリポジトリ。
galaxy_commit_id（デフォルト: master）：Galaxyが更新されるコミットID、タグ、ブランチ、またはその他の有効なGit参照。ブランチを指定すると、そのブランチの最新のコミットに更新されます。実際のコミットIDを使用することで、特定のバージョンに明示的にロックできます。
galaxy_force_checkout（デフォルト: no）：yesに設定すると、Galaxyリポジトリ内の変更されたファイルが破棄されます。
galaxy_clone_depth（デフォルト: 未設定）：git cloneを行う際の深さ。未指定のままにすると、全履歴がクローンされます。

追加の設定ファイル

生産Galaxyサーバーで一般的に使用されるオプションの設定ファイルはいくつかあり、変数から設定できます：

galaxy_dependency_resolvers: dependency_resolvers_conf.ymlファイルを設定します。サンプルXML設定を確認してください。
galaxy_container_resolvers: container_resolvers_conf.ymlファイルを設定します。サンプルXML設定を確認してください。
galaxy_job_metrics_plugins: job_metrics_conf.ymlファイルを設定します。サンプルXML設定を確認してください。

Galaxy 21.05以降、これらの機能のサンプル設定ファイルはXML形式ですが、YAML形式でもサポートされています。

galaxy_dependency_resolvers:
  - type: <XMLタグ名>
    <XML属性名>: <XML属性値>

例えば：

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

パス設定

Galaxyの特定のコンポーネントがファイルシステム上に置かれる場所を制御するためのオプション。

galaxy_venv_dir（デフォルト: <galaxy_server_dir>/.venv）：ロールはGalaxyが実行される[virtualenv][virtualenv]を作成し、ここで仮想環境が置かれます。
galaxy_virtualenv_command（デフォルト: virtualenv）：Galaxyの仮想環境を作成するために使用されるコマンド。Galaxy >= 20.01ではPython 3を使用する場合はpyvenvに設定します。
galaxy_virtualenv_python（デフォルト: $PATH上の最初のvirtualenvまたはpythonコマンドのpythonバイナリ）：仮想環境を作成する際に使用するpythonバイナリ。Galaxy < 20.01の場合、python2.7を使用してください（デフォルトでない場合）。Galaxy >= 20.01の場合、python3.5以上を使用します。
galaxy_config_dir（デフォルト: <galaxy_server_dir>）：「静的」設定ファイルに使用されるディレクトリ。
galaxy_mutable_config_dir（デフォルト: <galaxy_server_dir>）：Galaxyが書き込むことができる「可変」設定ファイルに使用されるディレクトリ。
galaxy_mutable_data_dir（デフォルト: <galaxy_server_dir>/database）：書き込み可能な「可変」データとキャッシュに使用されるディレクトリ。
galaxy_config_file（デフォルト: <galaxy_config_dir>/galaxy.ini）：Galaxyの主要な設定ファイル。

ユーザー管理と権限の分離

galaxy_separate_privileges（デフォルト: no）：権限分離モードを有効にします。
galaxy_user（デフォルト: ansibleを実行しているユーザー）：Galaxyが実行されるシステムユーザーの名前。
galaxy_privsep_user（デフォルト: root）：Galaxyのコード、設定ファイル、仮想環境（およびその中の依存関係）を所有するシステムユーザーの名前。
galaxy_group: Galaxyユーザーと権限分離ユーザーの共通グループ。設定されていて、galaxy_manage_pathsが有効な場合、Galaxy設定ファイルなどの機密情報を含むディレクトリは、一般読み取り可能ではなくグループ読み取りのみのアクセスを持ちます。そうでない場合、ディレクトリは一般読み取り可能に作成されます。

アクセスメソッド制御

ロールは、あなたが有効にした機能やターゲットホストへの接続方法によって異なるユーザーとしてタスクを実行する必要があります。デフォルトでは、ロールは適切なユーザーとしてタスクを実行するためにbecome（つまりsudo）を使用します。この動作を上書きすることは、defaults fileで説明されています。

systemd

systemdは、ほとんどのモダンLinuxディストリビューションで標準のシステム初期化デーモンです（およびこのロールによってサポートされているすべてのディストリビューション）。galaxy_manage_systemdが有効な場合、systemdにgalaxyサービスが設定され、Galaxyが実行されます。このサービスは自動的に開始され、システムがブートする際にも自動的に設定されます。rootユーザーとしてまたはsudoを使ってsystemctlユーティリティでGalaxyサービスを制御できます。

# systemctl start galaxy     # galaxyを開始
# systemctl reload galaxy    # "優雅な"リロードを試みる
# systemctl restart galaxy   # ハードリスタートを実行
# systemctl stop galaxy      # galaxyを停止

システム上のroot権限がない場合は、galaxy_systemd_rootをfalseに設定することでユーザーモードでsystemdを使用できます。その場合、上記のsystemctlコマンドに--userを追加して、ユーザーモードでsystemdと対話します。

エラードキュメント

galaxy_errordocs_dir: このディレクトリにGalaxyスタイルのHTTP 413および502エラードキュメントをインストールします。502メッセージは、Galaxyがダウンしているときに管理者が~/maintでカスタムメッセージを作成できるようにするため、nginxサーバー側のインクルードを使用します。nginxは、これらのエラードキュメントを提供するために別途設定する必要があります。
galaxy_errordocs_server_name（デフォルト: Galaxy）：502ページに"galaxy_errdocs_server_nameにアクセスできません"というメッセージを表示するために使用されます。
galaxy_errordocs_prefix（デフォルト: /error）：エラードキュメントのルートへのウェブ側パス。

その他のオプション

galaxy_admin_email_to: 設定されている場合、Galaxyが更新されたときにこのアドレスにメールを送信します。管理されたホストでメールが適切に設定されていると仮定します。
galaxy_admin_email_from: 上記のメールを送信するためのアドレス。

依存関係

なし

例プレイブック

基本

すべてのデフォルトオプションでローカルシステムにGalaxyをインストールします：

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

Ansibleのバージョンが>= 2.10.4の場合、ansible-playbook playbook.ymlを実行するときに追加の引数-u $USERを指定する必要があります。さもなければエラーが表示されます。

インストールが完了したら、以下の手順を実行できます。

$ cd /srv/galaxy
$ sh run.sh

ベストプラクティス

現在の本番サーバーベストプラクティスに従ってGalaxyをインストールします：

Galaxyのコード（クローン）は「クリーン」です：設定や可変データはクローンの下に存在しません。
Galaxyのコードと静的設定は権限分離されています：Galaxyを実行するユーザーが所有したり書き込みできない。
設定ファイルは一般に読み取り可能ではありません。
PostgreSQLがバックエンドデータベースとして使用されています。
18.01以降のスタイルYAML設定が使用されています。
2つのjob handler mulesが起動されています。
AnsibleによってGalaxyのコードまたは設定が更新されると、galaxyctlまたはsystemctl restart galaxy-*を使用して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:
          # リスニングオプション
          bind: "unix:{{ galaxy_mutable_config_dir }}/gunicorn.sock"
          # パフォーマンスオプション
          workers: 2
          # gunicornに渡されるその他のオプション
          # これはREMOTE_USERなどの「安全」ヘッダーの設定を許可します
          # https://docs.gunicorn.org/en/stable/settings.html#forwarded-allow-ips
          extra_args: '--forwarded-allow-ips="*"'
          # これにより、GunicornがGalaxyをフォークする前に完全に開始でき、より速くなります。
          # 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: 依存関係のインストール
      apt:
        name:
          - sudo
          - git
          - make
          - python3-venv
          - python3-setuptools
          - python3-dev
          - python3-psycopg2
          - gcc
          - acl
          - gnutls-bin
          - libmagic-dev
      become: yes
  roles:
    - role: galaxyproject.postgresql
      become: yes
    - role: galaxyproject.postgresql_objects
      become: yes
      become_user: postgres
    - role: galaxyproject.galaxy