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

Attempt to reduce duplication in the proxy documentation through the use

Browse Source 
of includes, move the multi-config-file discussion to a common page.
This commit is contained in:
Nate Coraor
2018-01-12 16:44:40 -05:00
parent f4131b8d2b
commit 5fcefe404f
6 changed files with 330 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/admin/_inc_proxy_prereq.rst
+22
View File
@@ -0,0 +1,22 @@
This documentation should be used in conjunction with the `Scaling and Load Balancing` documentation, which you should
familiarize yourself with prior to setting up your proxy.
You will need to ensure that inbound (and outbound) traffic on the HTTP (TCP port 80) and HTTPS (TCP port 443) ports is
permitted by your server's firewall/security.
**Documentation Conventions:**
For the purposes of this example, we assume that:
- **Debian** refers to any *Debian*-based Linux distribution (including Ubuntu)
- **EL** refers to any *RedHat Enterprise Linux*-based Linux distribution (including CentOS)
- the Galaxy server is installed at ``/srv/galaxy/server``
- |PROXY| runs as the user ``www-data`` (this is the default under Debian)
- Galaxy runs as the user ``galaxy`` with primary group ``galaxy``
- Galaxy is served from the hostname ``galaxy.example.org``
Throughout the configuration examples in this document, in order to avoid repetition, ``#...`` is used to denote a
location where existing or previously given configuration statements would appear.
.. danger:: Please note that Galaxy's files - code, datasets, and so forth - should *never* be located on disk inside
|PROXY|'s document root. By default, this would expose all of Galaxy (including datasets) to anyone on the web.
doc/source/admin/_inc_proxy_serving_root.rst
+10
View File
@@ -0,0 +1,10 @@
This configuration assumes that Galaxy will be the only site on your server using the given hostname (e.g.
``https://galaxy.example.org``).
Beginning with Galaxy Release 18.01, the default application server that Galaxy runs under is uWSGI. Because of this,
the native high performance uWSGI protocol should be used for communication between |PROXY| and Galaxy, rather
than HTTP. Legacy instructions for proxying via HTTP can be found in the `Galaxy Release 17.09 proxy documentation`_.
Since |PROXY| is more efficient than uWSGI at serving static content, it is best to serve it directly, reducing the load
on the Galaxy process and allowing for more effective compression (if enabled), caching, and pipelining. Directives to
do so are included in the example below.
doc/source/admin/_inc_proxy_ssl.rst
+25
View File
@@ -0,0 +1,25 @@
The use of SSL is **strongly encouraged** to avoid exposure of confidential information such as datasets and user
credentials to eavesdroppers. The instructions in this document are for setting up an SSL-enabled Galaxy server.
When setting up an SSL server, simply enabling SSL with the default options is not enough to have a secure server. In
most cases, the configuration is weak and vulnerable to one or more of the multitude of SSL attacks that have been
recently prevalent. The `Qualys SSL/TLS Deployment Best Practices`_ is an excellent and up-to-date guide covering
everything necessary for securing an SSL server. In addition, the `Mozilla SSL Configuration Generator`_ can provide you
with a best practices config tailored to your desired security level and software versions.
Finally, Google's `PageSpeed Insights`_ tool is helpful for determining how you can improve responsiveness as related to
proxying, such as verifying that caching and compression are configured properly.
If you need to run more than one site on your Galaxy server, there are two options:
- Run them on the same server but serve them on different hostnames
- Serve them from different URL prefixes on a single hostname
The former option is typically cleaner, but if serving more than one SSL site, you will need an SSL certificate with
subjectAltNames_ for each hostname served by the server.
.. _Qualys SSL/TLS Deployment Best Practices: https://www.ssllabs.com/projects/best-practices/
.. _Mozilla SSL Configuration Generator: https://mozilla.github.io/server-side-tls/ssl-config-generator/
.. _PageSpeed Insights: https://developers.google.com/speed/pagespeed/insights/
.. _subjectAltNames: http://wiki.cacert.org/FAQ/subjectAltName
doc/source/admin/apache.md
+56 -125
View File
@@ -1,25 +1,50 @@
```eval_rst
.. |PROXY| replace:: Apache
```
# Proxying Galaxy with Apache
For various reasons (performance, authentication, etc.) in a production environment, it's recommended to run Galaxy
behind a web server proxy. Although any proxy could work, Apache is a common choice. Alternatively, we use
[nginx](http://nginx.net/) for our public sites and open source infrastructure, and [details are
available](nginx.html) for it, too.
In a production environment, it is recommended to run Galaxy behind a proxy web server for performance and security
reasons. The proxy server sits between clients and your Galaxy server, relaying requests between them and offloading
some of the more menial and resource-intensive tasks.
Currently, the only recommended way to run Galaxy with Apache is using `mod_rewrite`, `mod_proxy`, and
`mod_proxy_uwsgi`. These modules must be enabled in the Apache config. The main proxy directives, `ProxyRequests` and
`ProxyVia` do **not** need to be enabled.
[The Apache HTTP Server][apache] is a widely deployed and very featureful general purpose web server with mature
proxying capabilities.
Instructions for [proxying with NGINX](nginx.html), which is the proxy server used by The Galaxy Project's public
servers, [usegalaxy.org][main] ("Main") and [Test][test], as well as the [Docker Galaxy project][docker-galaxy], are
also available.
[apache]: https://httpd.apache.org/
[main]: https://galaxyproject.org/main/
[test]: https://galaxyproject.org/test/
[docker-galaxy]: https://github.com/bgruening/docker-galaxy-stable
## Prerequisites
Make sure that inbound (and outbound) traffic to the TCP protocol HTTP on port 80 (and HTTPS on port 443 if using SSL)
is permitted by your server's firewall/security.
```eval_rst
.. include:: _inc_proxy_prereq.rst
```
These directions are written for Apache 2.4+. Apache 2.4 for Enterprise Linux (EL) 6 can be obtained from the [CentOS
SCLo SIG Repo](https://wiki.centos.org/SpecialInterestGroup/SCLo/CollectionsList).
### Apache Proxy Prerequisites
Currently, the only recommended way to proxy Galaxy with Apache is using `mod_rewrite`, `mod_proxy`, and
`mod_proxy_uwsgi`. These modules must be enabled in the Apache config. The main proxy directives, `ProxyRequests` and
`ProxyVia` do **not** need to be enabled.
Additionally, these directions are written for Apache 2.4+. Apache 2.4 for EL 6 can be obtained from the [CentOS SCLo
SIG Repo][sclo-sig-repo]. Otherwise, your system package manager's version of Apache should be suitable. On EL, you will
need to enable the [EPEL][epel] repository to obtain the `mod_proxy_uwsgi` package.
```eval_rst
.. caution:: ``mod_uwsgi`` is not the same module as ``mod_proxy_uwsgi``. The former is the old and unsupported module.
Be sure that you have installed ``mod_proxy_uwsgi``.
```
Ensure that the `mod_headers`, `mod_rewrite`, `mod_proxy`, and `mod_proxy_uwsgi` modules are loaded. Although not
required, the configuration examples also use `mod_deflate` and `mod_expires` for increased client/server performance,
so these should also be enabled. On Debian-based Linux distributions, you can do this with:
so these should also be enabled.
On Debian you can install the necessary packages and enable the modules this with the following:
```shell-session
# apt-get install apache2 libapache2-mod-proxy-uwsgi
@@ -38,68 +63,34 @@ To activate the new configuration, you need to run:
service apache2 restart
```
On EL-based distributions, you will need to enable the [EPEL](https://fedoraproject.org/wiki/EPEL) repository and then:
And on EL:
```shell-session
# yum install httpd mod_proxy_uwsgi
# echo "LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so" > /etc/httpd/conf.modules.d/10-proxy-uwsgi.conf
```
For the purposes of this example, we assume that:
- the Galaxy server is installed at `/srv/galaxy/server`
- Apache runs as the user `www-data` (this is the default under Debian-based Linux distributions)
- Galaxy runs as the user `galaxy` with primary group `galaxy`
- Galaxy is served from the hostname `galaxy.example.org`
Throughout the configuration examples in this document, in order to avoid repetition, `#...` is used to denote a location
where existing or previously given configuration statements would appear.
```eval_rst
.. warning:: Please note that Galaxy should *never* be located on disk inside Apache's `DocumentRoot`. By default, this
would expose all of Galaxy (including datasets) to anyone on the web.
```
[sclo-sig-repo]: https://wiki.centos.org/SpecialInterestGroup/SCLo/CollectionsList
[epel]: https://fedoraproject.org/wiki/EPEL
## Basic configuration
The use of SSL is **strongly encouraged** to avoid exposure of confidential information such as datasets and user
credentials to eavesdroppers. The instructions in this document are for setting an SSL-enabled Galaxy server.
When setting up an SSL server, simply enabling SSL with the default options is not enough. In most cases, the
configuration is weak and vulnerable to one or more of the multitude of SSL attacks that have been recently prevalent.
The [Qualys SSL/TLS Deployment Best Practices](https://www.ssllabs.com/projects/best-practices/) is an excellent and
up-to-date guide covering everything necessary for securing an SSL server. In addition, the [Mozilla SSL Configuration
Generator](https://mozilla.github.io/server-side-tls/ssl-config-generator/) can provide you with a best practices config
tailored to your desired security level and software versions.
Finally, Google's [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) tool is helpful for
determining how you can improve responsiveness as related to proxying, such as verifying that caching and compression
are configured properly.
If you need to run more than one site on your Galaxy server, there are two options:
- Run them on the same server but serve them on different hostnames
- Serve them from different URL prefixes on a single hostname
The former option is typically cleaner, but if serving more than one SSL site, you will need an SSL certificate with
[subjectAltName](http://wiki.cacert.org/FAQ/subjectAltName)s for each hostname served by the server.
```eval_rst
.. include:: _inc_proxy_ssl.rst
```
### Serving Galaxy at the Web Server Root
This configuration assumes that Galaxy will be the only site on your server using the given hostname (e.g.
`https://galaxy.example.org`).
Beginning with Galaxy Release 18.01, the default application server that Galaxy runs under is uWSGI. Because of this,
the native high performance uWSGI protocol should be used for communication between the proxy server and Galaxy, rather
than HTTP. Legacy instructions for proxying via HTTP can be found in the [Galaxy Release 17.09 Apache
documentation](https://docs.galaxyproject.org/en/release_17.09/admin/special_topics/apache.html).
Since Apache is more efficient than uWSGI at serving static content, it is best to serve it directly, reducing the load
on the Galaxy process and allowing for more effective compression (if enabled), caching, and pipelining. Directives to
do so are included in the example below.
```eval_rst
.. include:: _inc_proxy_serving_root.rst
.. _Galaxy Release 17.09 Proxy Documentation: https://docs.galaxyproject.org/en/release_17.09/admin/special_topics/apache.html
```
The following configuration is not exhaustive, only the portions most relevant to serving Galaxy are shown, these should
be incorporated with your existing/default Apache config as is appropriate for your server:
be incorporated with your existing/default Apache config as is appropriate for your server. Notably, the Apache package
you installed most likely has a multi-file config layout. If you are not already familiar with that layout and where
best to place your configuration, you can learn more in the [Proxy Package Layouts](proxy_package_layouts.html)
documentation.
```apache
SSLProtocol all -SSLv3
@@ -184,74 +175,14 @@ uWSGI socket path. With the default configuration, uWSGI will bind to a random T
a fixed value as described in the [Scaling and Load Balancing](scaling.html) documentation. If using a UNIX domain
socket, be sure to pay particular attention to the discussion of users and permissions.
### Implementation-specific Notes
It is possible to perform the entire configuration in the main Apache configuration file, however, Apache packages as
provided by Linux distribution package managers typically provide a slightly more complex layout that is designed to
prevent conflicts in the main Apahce config file when updating the package.
On Debian-based Linux distributions (Debian, Ubuntu, etc.), the Apache package's default configuration in
`/etc/apache2/apache2.conf` contains two include directives:
- One which includes any configuration files with the `.conf` extension in the `/etc/apache2/conf-enabled` directory,
which contains symlinks to `/etc/apache2/confs-available`, where you would place global (non-VirtualHost)
configuration directives.
- One which includes all files in the `/etc/apache2/sites-enabled` directory, which contains symlinks to
`/etc/apache2/sites-available`, where you would place the `<VirtualHost>` configurations for websites hosted by this
Apache server.
On EL-based Linux distributions (RedHat Enterprise Linux, CentOS, etc.), the Apache package's default configuration in
`/etc/httpd/conf/httpd.conf` contains a directive in that includes any configuration files with the `.conf` extension in
the `/etc/httpd/conf.d` directory.
Thus, you might create:
- `/etc/httpd/conf.d/galaxy_options.conf` on Debian-based distributions
- `/etc/apache2/confs-available/galaxy.conf` on Debian-based distributions
With the global configuration directives:
```apache
SSLProtocol all -SSLv3
SSLCipherSuite ...
#...
```
Then for the site configurations, you might create:
- `/etc/httpd/conf.d/galaxy_site.conf` on EL-based distributions
- `/etc/apache2/sites-available/galaxy` on Debian-based distributions
With the `<VirtualHost>` blocks:
```apache
<VirtualHost _default_:80>
Redirect permanent / https://galaxy.example.org
</VirtualHost>
<VirtualHost _default_:443>
SSLEngine on
SSLCertificateFile /etc/apache2/ssl/server.crt
SSLCertificateKeyFile /etc/apache2/ssl/server.key
#...
</VirtualHost>
```
On Debian-based distribution, you'd then need to symlink the configs with (or do it by hand with `ln -s`):
```shell-session
# a2enconf galaxy
# a2ensite galaxy
```
### Additional Notes
- **Do not** simply copy the SSL configuration directives and expect them to work on your server or to be secure! These
are provided as examples of some of the best practices as of the time of writing, but will not always be up to date.
Use the guides referenced in [basic configuration](#basic-configuration) section to configure SSL properly.
- If your existing Apache configuration contains a line or included config file defining a default server, be sure to
disable it by commenting its `<VirtualHost>` or preventing its inclusion (under Debian-based operating systems, this
is done by removing its symlink from `/etc/apache2/sites-enabled`).
disable it by commenting its `<VirtualHost>` or preventing its inclusion (under Debian this is done by removing its
symlink from `/etc/apache2/sites-enabled`).
- `ProxyTimeout` can be adjusted as appropriate for your site. This is the amount of time allowed for communication
between Apache and uWSGI to block while waiting for a response from Galaxy, and is useful for holding client (browser)
connections while uWSGI is restarting Galaxy subprocesses or Galaxy is performing a slow operation.
@@ -328,9 +259,9 @@ Apache can assume this task instead and as an added benefit, speed up downloads.
still check with Galaxy to ensure that the requesting user has permission to access the dataset before sending it.
To enable it, you must first install `mod_xsendfile`. This is usually available via your package manager
(`libapache2-mod-xsendfile` on Debian-based distributions and `mod_xsendfile` from EPEL on EL-based distributions). Once
installed, add the appropriate `LoadModule` directive to your Apache configuration (`LoadModule xsendfile_module
/path/to/mod_xsendfile.so`, but both the Debian and EPEL packages do this for you upon installation).
(`libapache2-mod-xsendfile` on Debian and `mod_xsendfile` from EPEL on EL). Once installed, add the appropriate
`LoadModule` directive to your Apache configuration (`LoadModule xsendfile_module /path/to/mod_xsendfile.so`, but both
the Debian and EPEL packages do this for you upon installation).
The, add `XSendFile` directives to your proxy configuration:
doc/source/admin/nginx.md
+45 -114
View File
@@ -1,73 +1,64 @@
```eval_rst
.. |PROXY| replace:: nginx
```
# Proxying Galaxy with NGINX
[NGINX](http://nginx.org/en/) is a lightweight http server designed with high performance proxying in mind. The public
Galaxy sites ([Main](https://galaxyproject.org/main/) and [Test](https://galaxyproject.org/test/)) as well as the
[Docker Galaxy project](https://github.com/bgruening/docker-galaxy-stable) use nginx to proxy rather than Apache for its
simple, fast load balancing and other features.
In a production environment, it is recommended to run Galaxy behind a proxy web server for performance and security
reasons. The proxy server sits between clients and your Galaxy server, relaying requests between them and offloading
some of the more menial and resource-intensive tasks.
[NGINX][nginx] is a lightweight HTTP server designed with high performance proxying in mind. The Galaxy Project's public
servers, [usegalaxy.org][main] ("Main") and [Test][test], as well as the [Docker Galaxy project][docker-galaxy] use
NGINX, rather than Apache, to proxy Galaxy. NGINX was chosen for its simple, fast load balancing and other
proxy-oriented features.
Instructions for [proxying with Apache](apache.html) are also available.
[nginx]: http://nginx.org/en/
[main]: https://galaxyproject.org/main/
[test]: https://galaxyproject.org/test/
[docker-galaxy]: https://github.com/bgruening/docker-galaxy-stable
## Prerequisites
Make sure that inbound (and outbound) traffic to the TCP protocol HTTP on port 80 (and HTTPS on port 443 if using SSL)
is permitted by your server's firewall/security.
For the purposes of this example, we assume that:
- the Galaxy server is installed at `/srv/galaxy/server`
- nginx runs as the user `www-data` (this is the default under Debian-based Linux distributions)
- Galaxy runs as the user `galaxy` with primary group `galaxy`
- Galaxy is served from the hostname `galaxy.example.org`
Throughout the configuration examples in this document, in order to avoid repetition, `#...` is used to denote a location
where existing or previously given configuration statements would appear.
```eval_rst
.. warning:: Please note that Galaxy should *never* be located on disk inside nginx's document root. By default, this
would expose all of Galaxy (including datasets) to anyone on the web.
.. include:: _inc_proxy_prereq.rst
```
### NGINX Proxy Prerequisities
If you plan to use nginx to handle your file uploads, you will (most likely) not be able to use your package manager's
version of nginx. The [Receiving Files With NGINX](#receiving-files-with-nginx) section explains this in detail and
provides some options for installing *nginx + upload module* packages maintained by the Galaxy Committers Team.
Otherwise, your system package manager's version of nginx should be suitable. Under Debian, the
[nginx-light][nginx-light] package contains all the necessary modules used in this guide. On EL, the [EPEL][epel]
version of nginx is suitable.
[nginx-light]: https://packages.debian.org/search?keywords=nginx-light
[epel]: https://fedoraproject.org/wiki/EPEL
## Basic Configuration
The use of SSL is **strongly encouraged** to avoid exposure of confidential information such as datasets and user
credentials to eavesdroppers. The instructions in this document are for setting an SSL-enabled Galaxy server.
When setting up an SSL server, simply enabling SSL with the default options is not enough. In most cases, the
configuration is weak and vulnerable to one or more of the multitude of SSL attacks that have been recently prevalent.
The [Qualys SSL/TLS Deployment Best Practices](https://www.ssllabs.com/projects/best-practices/) is an excellent and
up-to-date guide covering everything necessary for securing an SSL server. In addition, the [Mozilla SSL Configuration
Generator](https://mozilla.github.io/server-side-tls/ssl-config-generator/) can provide you with a best practices config
tailored to your desired security level and software versions.
Finally, Google's [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) tool is helpful for
determining how you can improve responsiveness as related to proxying, such as verifying that caching and compression
are configured properly.
If you need to run more than one site on your Galaxy server, there are two options:
- Run them on the same server but serve them on different hostnames
- Serve them from different URL prefixes on a single hostname
The former option is typically cleaner, but if serving more than one SSL site, you will need an SSL certificate with
[subjectAltName](http://wiki.cacert.org/FAQ/subjectAltName)s for each hostname served by the server.
```eval_rst
.. include:: _inc_proxy_ssl.rst
```
### Serving Galaxy at the Web Server Root
This configuration assumes that Galaxy will be the only site on your server using the given hostname (e.g.
`https://galaxy.example.org`).
Beginning with Galaxy Release 18.01, the default application server that Galaxy runs under is uWSGI. Because of this,
the native high performance uWSGI protocol should be used for communication between the proxy server and Galaxy, rather
than HTTP. Legacy instructions for proxying via HTTP can be found in the [Galaxy Release 17.09 nginx
documentation](https://docs.galaxyproject.org/en/release_17.09/admin/special_topics/nginx.html).
```eval_rst
.. include:: _inc_proxy_serving_root.rst
.. _Galaxy Release 17.09 Proxy Documentation: https://docs.galaxyproject.org/en/release_17.09/admin/special_topics/nginx.html
```
uWSGI protocol support is built in to nginx, so (unlike Apache) no extra modules or recompiling should be required.
Since nginx is more efficient than uWSGI at serving static content, it is best to serve it directly, reducing the load
on the Galaxy process and allowing for more effective compression (if enabled), caching, and pipelining. Directives to
do so are included in the example below.
The following configuration is not exhaustive, only the portions most relevant to serving Galaxy are shown, these should
be incorporated with your existing/default nginx config as is appropriate for your server:
be incorporated with your existing/default nginx config as is appropriate for your server. Notably, the nginx package
you installed most likely has a multi-file config layout. If you are not already familiar with that layout and where
best to place your configuration, you can learn more in the [Proxy Package Layouts](proxy_package_layouts.html)
documentation.
```nginx
http {
@@ -171,74 +162,14 @@ uWSGI socket path. With the default configuration, uWSGI will bind to a random T
a fixed value as described in the [Scaling and Load Balancing](scaling.html) documentation. If using a UNIX domain
socket, be sure to pay particular attention to the discussion of users and permissions.
### Implementation-specific Notes
It is possible to perform the entire configuration in the main nginx configuration file (typically
`/etc/nginx/nginx.conf`), however, nginx packages as provided by Linux distribution package managers typically provide a
slightly more complex layout that is designed to prevent conflicts in `nginx.conf` when updating the package.
On Debian-based Linux distributions (Debian, Ubuntu, etc.), the nginx package's default configuration contains two
include directives in the `http {}` block:
- One which includes any configuration files with the `.conf` extension in the `/etc/nginx/conf.d` directory, where you
would place directives that belong in the `http {}` block.
- One which includes all files in the `/etc/nginx/sites-enabled` directory, which contains symlinks to
`/etc/nginx/sites-available`, where you would place the `server {}` configurations for websites hosted by this nginx
server.
On EL-based Linux distributions (RedHat Enterprise Linux, CentOS, etc.), the EPEL nginx package's default configuration
contains a directive in the `http {}` block that includes any configuration files with the `.conf` extension in the
`/etc/nginx/conf.d` directory.
Thus, on both Debian- and EL-based distributions, you might put the `http` directives in
`/etc/nginx/conf.d/galaxy_http_options.conf`. Note that these are **not** enclosed in an `http {}` block themselves, as
they are already enclosed by the `http {}` block in `/etc/nginx/nginx.conf`:
```nginx
uwsgi_read_timeout 180;
client_max_body_size 10g;
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
#...
```
Then for the site configurations, you might create:
- `/etc/nginx/conf.d/galaxy_site.conf` on EL-based distributions
- `/etc/nginx/sites-available/galaxy` on Debian-based distributions
With the `server {}` blocks (again, not enclosed in an `http {}`):
```nginx
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
#...
}
server {
listen 443 default_server;
listen [::]:443 default_server;
server_name _;
#...
}
```
On Debian-based distribution, you'd then need to symlink the config with:
```shell-session
# ln -s /etc/nginx/sites-available/galaxy /etc/nginx/sites-enabled/galaxy
```
### Additional Notes
- **Do not** simply copy the SSL configuration directives and expect them to work on your server or to be secure! These
are provided as examples of some of the best practices as of the time of writing, but will not always be up to date.
Use the guides referenced in [basic configuration](#basic-configuration) section to configure SSL properly.
- If your existing nginx configuration contains a line or included config file defining a default server, be sure to
disable it by commenting its `server {}` or preventing its inclusion (under Debian-based operating systems, this
is done by removing its symlink from `/etc/nginx/sites-enabled`).
disable it by commenting its `server {}` or preventing its inclusion (under Debian this is done by removing its
symlink from `/etc/nginx/sites-enabled`).
- `uwsgi_read_timeout` can be adjusted as appropriate for your site. This is the amount of time allowed for
communication between nginx and uWSGI to block while waiting for a response from Galaxy, and is useful for holding
client (browser) connections while uWSGI is restarting Galaxy subprocesses or Galaxy is performing a slow operation.
doc/source/admin/proxy_package_layout.rst
+172
View File
@@ -0,0 +1,172 @@
Proxy Package Layouts
========================================
Every software package has a suggested filesystem layout, and proxy servers like Apache and NGINX are no exception.
However, Linux distribution package maintainers often have their own opinions about layout, especially with respect to
following a layout standard or scheme employed by their particular distribution.
Thus, although you can configure the proxy server entirely within its primary configuration file, if you have installed
the proxy via your system package manager, this may not be the best idea. The primary config file in the cases of both Apache
and nginx under both Debian-based distributions and Enterprise Linux-based distributions contains various *include*
directives designed to allow you to place your configuration in files that are entirely controlled by you. This helps to
avoid conflicts in the primary config file when the package is upgraded.
.. hint::
Primary configuration files can be found at:
- nginx (both EL and Debian): ``/etc/nginx/nginx.conf``
- Apache:
- EL: ``/etc/httpd/conf/httpd.conf``
- Debian: ``/etc/apache2/apache2.conf``
Package Layout Overviews
---------------------------
Debian
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Debian uses a very similar directory scheme for both nginx and Apache, where ``<server>`` is ``apache2`` or ``nginx``
and ``<component>`` is some configuration subcomponent:
- ``/etc/<server>/<component>-available`` for files containing configuration snippets for various instances of the given
component
- ``/etc/<server>/<component>-enabled`` for symbolic links to files in ``/etc/<server>/<component>-available`` for each
snippet that the administrator wishes to enable
``<component>-available`` is effectively a "repository" for configurations which are enabled by symbolic links in
``<component>-enabled``.
Both nginx and Apache use the component ``sites``, intended for individual website configurations. Apache additionally
uses the components ``mods`` and ``conf`` for module loading/configuration and general global configuration statements,
respectively. Nginx, lacking the ``mods`` and ``conf`` components, provides ``/etc/nginx/conf.d``
.. tip::
On Debian, the paths most relevant to our purposes are:
- nginx:
- ``/etc/nginx/conf.d/*.conf`` for general directives that belong in the ``http {}`` block
- ``/etc/nginx/sites-available/*`` for individual site configs
- ``/etc/nginx/sites-enabled/*`` to enable sites
- Apache:
- ``/etc/apache2/conf-available/*`` for general directives that belong in the ``http {}`` block
- ``/etc/apache2/conf-enabled/*`` to enable configs
- ``/etc/apache2/sites-available/*`` for individual site configs
- ``/etc/apache2/sites-enabled/*`` to enable sites
Enterprise Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EL's layout is simpler: both nginx and Apache provide a single configuration inclusion directory, where ``<server>`` is
``httpd`` or ``nginx``:
- ``/etc/<server>/conf.d/``
Apache additionally has a module configuration directory at ``/etc/httpd/conf.modules.d``
.. tip::
On EL, the paths most relevant to our purposes are:
- nginx: ``/etc/nginx/conf.d/*.conf``
- Apache: ``/etc/httpd/conf.d/*.conf``
NGINX
---------------------------
**Global option configuration:**
On both Debian and EL, you could create ``/etc/nginx/conf.d/galaxy_options.conf`` for global options intended for the
``http {}`` block. Because this file is included from within the ``http {}`` block, you would simply define directives
without enclosing them in any sort of block:
.. code-block:: nginx
uwsgi_read_timeout 180;
client_max_body_size 10g;
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
#...
**Site configuration:**
For the site configurations, you could create:
- ``/etc/nginx/sites-available/galaxy`` on Debian
- ``/etc/nginx/conf.d/galaxy_site.conf`` on EL
These files contain ``server {}`` blocks (again, not enclosed in an ``http {}``):
.. code-block:: nginx
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
#...
}
server {
listen 443 default_server;
listen [::]:443 default_server;
server_name _;
#...
}
On Debian, you'd then need to symlink the config with:
.. code-block:: shell-session
# ln -s /etc/nginx/sites-available/galaxy /etc/nginx/sites-enabled/galaxy
Apache
---------------------------
**Global option configuration:**
For the global options, you could create:
- ``/etc/apache2/confs-available/galaxy.conf`` on Debian
- ``/etc/httpd/conf.d/galaxy_options.conf`` on EL
With the global configuration directives:
.. code-block:: apache
SSLProtocol all -SSLv3
SSLCipherSuite ...
#...
**Site configuration:**
For the site configurations, you could create:
- ``/etc/apache2/sites-available/galaxy.conf`` on Debian
- ``/etc/httpd/conf.d/galaxy_site.conf`` on EL
With the ``<VirtualHost>`` blocks:
.. code-block:: apache
<VirtualHost _default_:80>
Redirect permanent / https://galaxy.example.org
</VirtualHost>
<VirtualHost _default_:443>
SSLEngine on
SSLCertificateFile /etc/apache2/ssl/server.crt
SSLCertificateKeyFile /etc/apache2/ssl/server.key
#...
</VirtualHost>
On Debian you'd then need to symlink the configs with (or do it by hand with `ln -s`):
.. code-block:: shell-session
# a2enconf galaxy
# a2ensite galaxy