opensource/galaxy
3
0
Fork 0
mirror of https://github.com/galaxyproject/galaxy.git synced 2026-09-24 16:30:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

WIP admin docs updates for 18.01

Browse Source
This commit is contained in:
Nate Coraor
2017-12-07 16:47:52 -05:00
parent 0664921e00
commit 8cf649b331
5 changed files with 78 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/admin/application_server.rst
-57
View File
@@ -1,57 +0,0 @@
Application Server
========================================
Overview
----------------------------
It is possible to run the Galaxy server in many different ways, including under different web application frameworks, or
as a standalone server with no web stack. For most of its modern life, prior to the 18.01 release, Galaxy used the
`Python Paste`_ web stack, and ran in a single process.
Beginning with Galaxy release 18.01, the default application server for new installations of Galaxy is `uWSGI`_, which
has numerous benefits:
- Written in C and designed to be high performance.
- Internal support for serving static content.
- Supports WebSockets, which allows for support of Galaxy Interactive Environments out of the box, removing the
dependency on Node.js.
- ...
In addition, uWSGI has been the recommended application server for production Galaxy servers for many years, but was not
previously provided with Galaxy.
What server am I running?
----------------------------
**Galaxy releases older than 18.01**
- If you start your server with the provided ``run.sh`` script, it is using Paste.
-
Unless it has been manually configured to run under uWSGI, your server is using Paste.
**Galaxy releases 18.01 and newer**
If you upgraded from
In any case, ``pgrep(1)`` or ``ps(1)`` should provide the answer, for example:
```sh-session
galaxy@server$ pgrep -af -u $EUID galaxy
16232 uwsgi --ini-paste config/galaxy.ini
16233 uwsgi --ini-paste config/galaxy.ini
17406 /srv/galaxy/venv/bin/python2.7 /srv/galaxy/venv/bin/uwsgi --yaml config/galaxy.yml
17419 /srv/galaxy/venv/bin/python2.7 /srv/galaxy/venv/bin/uwsgi --yaml config/galaxy.yml
17172 python ./scripts/paster.py serve config/galaxy.ini
```
The first 4 processes listed are uWSGI
If you are upgrading to Galaxy 18.01
from an older release, still have your ``galaxy.ini`` file in place, and have not manually switched to another stack
(such as uWSGI), Galaxy will continue to run under Paste.
.. _Python Paste: http://paste.readthedocs.io/
.. _uWSGI: https://uwsgi-docs.readthedocs.io/
doc/source/admin/config.rst
+16 -7
View File
@@ -92,18 +92,27 @@ Additional configuration files and their purposes are:
.. _Data Managers documentation: https://galaxyproject.org/admin/tools/data-managers/
Configuration
Configuration Basics
----------------------------
- Configure ``config/reports.yml`` in the same manner as your main galaxy instance (i.e., same database connection, but different port). This is a uwsgi YAML configuration file and should contain a reports section with app-specific configuration (options described below).
- Edit ``config/galaxy.yml`` (copy it from ``config/galaxy.yml.sample`` if it does not exist) to make configuration
changes. This is a `uWSGI YAML configuration file`_ and should contain two sections, one named ``uwsgi`` for uWSGI and
one named ``galaxy`` for Galaxy.
- The default port for the reports application is ``9001``, and like Galaxy it only binds to localhost by default.
- ``database_connection`` should match the value used in your Galaxy configuration
- ``database_connection`` should point at a Postgres database, experimental support for MySQL is available but sqlite is not supported at all.
- The default port for the Galaxy web server is ``8080``, and it only binds to localhost by default. To configure
uWSGI to listen on all available network addresses, set ``http`` to ``0.0.0.0:<port>`` (e.g. ``http:
0.0.0.0:8080``).
- Some uWSGI options are required for uWSGI to run Galaxy properly and will be added to the ``uwsgi`` command line
by ``run.sh`` if not specified in ``galaxy.yml``.
- uWSGI has a `large number of options`_. The Galaxy documentation refers to some of them, but many additional
advanced deployment scenarios are available.
- Run reports in a uWSGI server with ``sh run_reports.sh``
- Use a web browser and go to the address you configured in ``reports.yml`` (defaults to http://localhost:9001/)
- Run Galaxy in a uWSGI server with ``GALAXY_UWSGI=1 sh run.sh``
- Use a web browser and go to the address you configured in ``galaxy.yml`` (defaults to http://localhost:8080/)
.. _uWSGI YAML configuration file: http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html
.. _large number of options: http://uwsgi-docs.readthedocs.io/en/latest/Options.html
.. ----------------------------
.. Configuration Options
.. ----------------------------
doc/source/admin/index.rst
+1
View File
@@ -6,6 +6,7 @@ This documentation is in the midst of being ported and unified based on resource
.. toctree::
:maxdepth: 2
config
production
cluster
scaling
doc/source/admin/reports.rst
+1 -1
View File
@@ -41,7 +41,7 @@ following (and more):
Configuration
----------------------------
- Configure ``config/reports.yml`` in the same manner as your main galaxy instance (i.e., same database connection, but different port). This is a uwsgi YAML configuration file and should contain a reports section with app-specific configuration (options described below).
- Configure ``config/reports.yml`` in the same manner as your main galaxy instance (i.e., same database connection, but different web server port). This is a uWSGI YAML configuration file and should contain a ``reports`` section with app-specific configuration (options described below).
- The default port for the reports application is ``9001``, and like Galaxy it only binds to localhost by default.
- ``database_connection`` should match the value used in your Galaxy configuration
doc/source/admin/scaling.md
+60 -43
View File
@@ -1,63 +1,80 @@
# Scaling and Load Balancing
The Galaxy framework is written in Python and makes extensive use of threads. However, one of the drawbacks of Python is the [Global Interpreter Lock](http://docs.python.org/c-api/init.html#thread-state-and-the-global-interpreter-lock), which prevents more than one thread from being on CPU at a time. Because of this, having a multi-core system will not improve the Galaxy framework's performance out of the box since Galaxy can use (at most) one core at a time. However, Galaxy can easily run in multiple separate processes, which solves this problem. For a more thorough explanation of this problem and why you will almost surely want to switch to the load balanced configuration if running for more than a small handful of users, see the [production configuration](production.html) page.
The Galaxy framework is written in Python and makes extensive use of threads. However, one of the drawbacks of Python is the [Global Interpreter Lock](http://docs.python.org/c-api/init.html#thread-state-and-the-global-interpreter-lock), which prevents more than one thread from being on CPU at a time. Because of this, having a multi-core system will not improve the Galaxy framework's performance out of the box since Galaxy can use (at most) one core at a time in its default configuration. However, Galaxy can easily run in multiple separate processes, which solves this problem. For a more thorough explanation of this problem and why you will almost surely want to switch to the multiprocess configuration if running for more than a small handful of users, see the [production configuration](production.html) page.
Just to be clear: increasing the values of `threadpool_workers` in `galaxy.yml` or the number of plugin workers in `job_conf.xml` will not make you Galaxy server much more responsive. The key to scaling Galaxy is the ability to run *multiple* Galaxy servers which co-operatively work on the same database.
A simple configuration:
* 1 "job handler" process - responsible for starting and monitoring jobs, submitting jobs to a cluster (if configured), and for setting metadata (externally or internally).
* 1 "web server" process - responsible for servicing web pages to users.
## Terminology
An advanced configuration:
* Multiple "job handler" processes.
* Multiple "web server" processes, proxied through a load-balancing capable web server (e.g. nginx or apache).
* **web worker** - Galaxy server process responsible for servicing web requests for the UI/API
* **job handler** - Galaxy server process responsible for starting and monitoring jobs, submitting jobs to a cluster (if configured), and for setting metadata (if not set on the cluster)
* **[uWSGI][uwsgi]** - Powerful application server written in C that implements the HTTP and Python WSGI protocols
* **[Mules][uwsgi-mules]** - uWSGI processes started after the main application (Galaxy) that can run separate code and receive messages from uWSGI web workers
* **[Zerg Mode][uwsgi-zerg-mode]** - uWSGI configuration where multiple copies of the same application can be started simultaneously in order to maintain availability during application restarts
* **[Emperor Mode][uwsgi-emperor-mode]** - uWSGI configuration where multiple distinct applications can be started by a single master uWSGI process
* **Webless Galaxy application** - The Galaxy application run as a standalone Python application with no web/WSGI server
* **[Paste][paste]** - Application server written in pure Python that implements the HTTP and Python WSGI protocols
### Web Server(s)
[uwsgi]: http://uwsgi-docs.readthedocs.io/
[uwsgi-mules]: http://uwsgi-docs.readthedocs.io/en/latest/Mules.html
[uwsgi-zerg-mode]: http://uwsgi-docs.readthedocs.io/en/latest/Zerg.html
[uwsgi-emperor-mode]: http://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
[paste]: http://paste.readthedocs.io/
There are a few different ways you can run multiple web server processes:
### Deployment Options
**Standalone Paste-based processes:**
* Pros:
* Simplest setup, especially if only using a single web server process
* No additional dependencies
* Proxy not required if only using a single web server process
* Cons:
* Not as resilient to failure
* Load balancing typically round-robin regardless of individual process load
* No dynamic scaling
There are multiple deployment strategies for the Galaxy application that you can choose from. The right one depends on the configuration of the infrastructure on which you are deploying.
**uWSGI:**
* Pros:
* Higher performance server than Paste
* Better scalability and fault tolerance
* Easier process management and Galaxy server restartability
* Cons:
* Requires uWSGI
#### uWSGI with jobs handled by web workers (default configuration)
Using uWSGI for production servers is recommended by the Galaxy team.
* Easily runs multiple processes by increasing `processes` config option
* Load balanced internally
* Speaks native uWSGI protocol supported by nginx and Apache or direct HTTP (and SSL)
* Written in C and designed to be high performance
* Supports WebSockets, which enable Galaxy Interactive Environments out-of-the-box without a proxy server or Node.js
* Incredibly featureful, supports a wide array of deployment scenarios
* The default as of Galaxy Release 18.01
* Jobs are handled by uWSGI web workers (but all Galaxy job features such as [running on a cluster](cluster.html) are still supported)
#### Standalone Paste-based processes
Under this strategy, jobs will be handled by the web worker that receives the job request from the UI/API. Having web processes handle jobs will negatively impact UI/API performance.
In `galaxy.ini`, define one or more `[server:...]` sections:
#### uWSGI for web serving with Mules as job handlers
```ini
[server:web0]
use = egg:Paste#http
port = 8080
host = 127.0.0.1
use_threadpool = true
threadpool_workers = 7
* Job handlers run as children of the uWSGI process
* Jobs are dispatched from web workers to job handlers via native *mule messaging*
* Jobs can only be dispatched to mules on the same host
* Trivially easy to enable (disabled by default for simplicity reasons)
[server:web1]
use = egg:Paste#http
port = 8081
host = 127.0.0.1
use_threadpool = true
threadpool_workers = 7
```
Under this strategy, job handling is offloaded to dedicated non-web-serving processes that are started and stopped directly by the master uWSGI process. As a benefit of using mule messaging, only job handlers that are alive will be selected to run jobs.
**uWSGI + Mule job handlers is the recommended deployment strategy** for Galaxy servers that run web servers and job handlers **on the same host**.
Two are shown, you should create as many as are suitable for your usage and hardware. On our eight-core server, I run six web server processes. You may find you only need one, which is a slightly simpler configuration.
#### uWSGI for web serving and Webless Galaxy applications as job handlers
* Galaxy is started as a standalone Python application with no web stack
* Jobs are dispatched from web workers to job handlers via the Galaxy database
* Jobs can be dispatched to job handlers running on any host
* The recommended deployment strategy for production Galaxy instances prior to 18.01
Like mules, under this strategy, job handling is offloaded to dedicated non-web-serving processes, but those processes are [managed by the administrator](#starting-and-stopping). Because the handler is randomly assigned by the web worker when the job is submitted via the UI/API, jobs may be assigned to dead handlers.
**uWSGI + Webless job handlers is the recommended deployment strategy** for Galaxy servers that run web servers and job handlers **on different hosts**.
#### Legacy Deployment Options
Certain deployment strategies were commonly used prior to the introduction of new features described above. These are still possible but should no longer be used.
##### uWSGI for web serving with Paste Galaxy applications as job handlers
This is essentially the same as **uWSGI + Webless job handlers** but needlessly starts handlers with a web stack. This was recommended before the Webless method existed
##### Paste for web serving with Paste or Webless job handlers
Unlike uWSGI, Paste cannot start multiple server processes on its own. Prior to uWSGI support, this was the only way to run multiple Galaxy processes, but each web worker and job handler process had to be configured and managed separately.
##### Paste web serving and job handling in a single process
This was the default configuration prior to the 18.01 Galaxy release and offered the simplest out-of-the-box setup at the expense of performance and scalability.
#### uWSGI