diff --git a/doc/source/admin/apache.md b/doc/source/admin/apache.md new file mode 100644 index 00000000000..50b7faf3c53 --- /dev/null +++ b/doc/source/admin/apache.md @@ -0,0 +1,410 @@ +# 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. + +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. + +## 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. + +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). + +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: + +```shell-session +# apt-get install apache2 libapache2-mod-proxy-uwsgi +# a2enmod headers deflate expires rewrite proxy proxy_uwsgi +Enabling module headers. +Considering dependency filter for deflate: +Module filter already enabled +Module deflate already enabled +Enabling module expires. +Enabling module rewrite. +Enabling module proxy. +Considering dependency proxy for proxy_uwsgi: +Module proxy already enabled +Enabling module proxy_uwsgi. +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: + +```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 reptition, `#...` 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. +``` + +## 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. + +### 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. + +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: + +```apache +SSLProtocol all -SSLv3 +SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256 +SSLHonorCipherOrder on +SSLCompression off +SSLSessionTickets off + +# OCSP stapling +SSLUseStapling on +SSLStaplingResponderTimeout 5 +SSLStaplingReturnResponderErrors off +SSLStaplingCache shmcb:/var/run/ocsp(128000) + + + Redirect permanent / https://galaxy.example.org + + + + SSLEngine on + SSLCertificateFile /etc/apache2/ssl/server.crt + SSLCertificateKeyFile /etc/apache2/ssl/server.key + + # Enable HSTS + Header always set Strict-Transport-Security "max-age=15552000; includeSubdomains" + + # use a variable for convenience + Define galaxy_root /srv/galaxy/server + + # don't decode encoded slashes in path info + AllowEncodedSlashes NoDecode + + # enable compression on all relevant types + AddOutputFilterByType DEFLATE text/html text/plain text/xml + AddOutputFilterByType DEFLATE text/css + AddOutputFilterByType DEFLATE application/x-javascript application/javascript application/ecmascript + AddOutputFilterByType DEFLATE application/rss+xml + AddOutputFilterByType DEFLATE application/xml + AddOutputFilterByType DEFLATE application/json + + # allow access to static content + + AllowOverride None + Require all granted + + + # Galaxy needs to know that this is https for generating URLs + RequestHeader set X-URL-SCHEME "%{REQUEST_SCHEME}e" + + # allow up to 3 minutes for Galaxy to respond to slow requests before timing out + ProxyTimeout 180 + + # proxy all requests not matching other locations to uWSGI + ProxyPass / unix:///srv/galaxy/var/uwsgi.sock|uwsgi:// + # or uWSGI on a TCP socket + #ProxyPass / uwsgi://127.0.0.1:4001/ + + # serve framework static content + RewriteEngine On + RewriteRule ^/static/style/(.*) ${galaxy_root}/static/style/blue/$1 [L] + RewriteRule ^/static/(.*) ${galaxy_root}/static/$1 [L] + RewriteRule ^/favicon.ico ${galaxy_root}/static/favicon.ico [L] + RewriteRule ^/robots.txt ${galaxy_root}/static/robots.txt [L] + + # enable caching on static content + + ExpiresActive On + ExpiresDefault "access plus 24 hours" + + + # serve visualization and interactive environment plugin static content + + AllowOverride None + Require all granted + + RewriteRule ^/plugins/(.+)/(.+)/static/(.*)$ ${galaxy_root}/config/plugins/$1/$2/static/$3 [L] + +``` + +Be sure to set `galaxy_root` to the path to your copy of Galaxy and modify the value of `ProxyPass /` to match your +uWSGI socket path. With the default configuration, uWSGI will bind to a random TCP socket, so you will need to set it to +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 `` 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 `` blocks: + +```apache + + Redirect permanent / https://galaxy.example.org + + + + SSLEngine on + SSLCertificateFile /etc/apache2/ssl/server.crt + SSLCertificateKeyFile /etc/apache2/ssl/server.key + #... + +``` + +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 `` or preventing its inclusion (under Debian-based operating systems, 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. +- If your Apache server is set up to use `mod_security`, you may need to modify the value of the `SecRequestBodyLimit`. + The default value on some systems will limit uploads to only a few kilobytes. +- Some Galaxy URLs contain encoded slashes (%2F) in the path and Apache will not serve these URLs by default, which is + the reason for inclusion of the `AllowEncodedSlashes` directive. Note: The `NoDecode` value was added in Apache2 + 2.2.18, which is newer than EL 6's provided 2.2.15. +- If you must serve Galaxy without SSL, you would simply replace the `443` with `80` in the SSL `VirtualHost` block + and remove the non-SSL block and all SSL directives. +- If the proxy works but you are getting 404 errors for Galaxy's static content, be sure that the user that Apache runs + as has access to Galaxy's `static/` directory (and all its parent directories) on the filesystem. You can test this on + the command line with e.g. `sudo -u www-data ls /srv/galaxy/server/static`. + +### Serving Galaxy at a URL Prefix + +It may be necessary to serve Galaxy from an address other than the web server root (`https://www.example.org/galaxy`), +instead of `https://galaxy.example.org`). To do this, you need to make the following changes to the configuration in the +previous section: + +1. In the Apache config, prefix all of the location directives with your prefix, like so: + + ```apache + #... + + # proxy all requests not matching other locations to uWSGI + ProxyPass /galaxy unix:///srv/galaxy/var/uwsgi.sock|uwsgi:// + # or uWSGI on a TCP socket + #ProxyPass /galaxy uwsgi://127.0.0.1:4001/ + + # serve framework static content + RewriteEngine On + RewriteRule ^/galaxy/$ /galaxy [R,L] + RewriteRule ^/galaxy/static/style/(.*) ${galaxy_root}/static/style/blue/$1 [L] + RewriteRule ^/galaxy/static/(.*) ${galaxy_root}/static/$1 [L] + RewriteRule ^/galaxy/favicon.ico ${galaxy_root}/static/favicon.ico [L] + RewriteRule ^/galaxy/robots.txt ${galaxy_root}/static/robots.txt [L] + ``` + +2. The Galaxy application needs to be aware that it is running with a prefix (for generating URLs in dynamic pages). + This is accomplished by configuring uWSGI and Galaxy (the `uwsgi` and `galaxy` sections in `config/galaxy.yml` + respectively) like so and restarting Galaxy: + + ```yaml + uwsgi: + #... + socket: unix:///srv/galaxy/var/uwsgi.sock + mount: /galaxy=galaxy.webapps.galaxy.buildapp:uwsgi_app() + manage-script-name: true + # `module` MUST NOT be set when `mount` is in use + #module: galaxy.webapps.galaxy.buildapp:uwsgi_app() + + galaxy: + #... + cookie_path: /galaxy + ``` + + `cookie_path` should be set to prevent Galaxy's session cookies from clobbering each other if you are running more + than one instance of Galaxy under different URL prefixes on the same hostname. + + Be sure to consult the [Scaling and Load Balancing](scaling.html) documentation, other options unrelated to proxying + should also be set in the `uwsgi` section of the config. + +## Advanced Configuration Topics + +### Sending Files With Apache + +Galaxy sends files (e.g. dataset downloads) by opening the file and streaming it in chunks through the proxy server. +However, this ties up the Galaxy process, which can impact the performance of other operations (see [Production Server +Configuration](production.html) for a more in-depth explanation). + +Apache can assume this task instead and as an added benefit, speed up downloads. This is accomplished through the use of +`mod_xsendfile`, a 3rd-party Apache module. Dataset security is maintained in this configuration because Apache will +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). + +The, add `XSendFile` directives to your proxy configuration: + +```apache + + XSendFile on + XSendFilePath / + +``` + +Next, edit `galaxy.yml` and make the following change before restarting Galaxy: + +```yaml +galaxy: + # ... + apache_xsendfile: true +``` + +For this to work, the user under which your Apache server runs will need read access to Galaxy's `files_path` directory +(by default, `database/files/`) and its contents. This is most easily done by adding the Apache user to the Galaxy user's +primary group and setting the `umask(2)` to create files with the group read permission set. If you start Galaxy from +the command line, you can do this like so: + +```shell-session +admin@server$ sudo usermod -a -G galaxy www-data # add `www-data` user to `galaxy` group +admin@server$ sudo -iu galaxy +galaxy@server$ umask 027 +galaxy@server$ sh run.sh +``` + +If you start Galaxy from supervisord, you can set the `umask` option in the [program +section](http://supervisord.org/configuration.html#program-x-section-settings) after adding the Apache user to the Galaxy +group as shown above. + +### External user authentication + +- [Apache for External Authentication](https://galaxyproject.org/admin/config/apache-external-user-auth/) +- [Built-in Galaxy External Authentication](authentication.html) + +#### Display Sites + +Display sites such as UCSC work not by sending data directly from Galaxy to UCSC via the client's browser, but by +sending UCSC a URL to the data in Galaxy that the UCSC server will retrieve data from. Since enabling authentication +will place **all** of Galaxy behind authentication, such display sites will no longer be able to access data via that +URL. If `display_servers` is set to a non-empty value in `$galaxy_root/config/galaxy.yml`, this tells Galaxy it should +allow the named servers access to data in Galaxy. However, you still need to configure Apache to allow access to the +datasets. An example config is provided here that allows the UCSC Main/Test backends: + +```apache + + Satisfy Any + Order deny,allow + Deny from all + Allow from hgw1.cse.ucsc.edu + Allow from hgw2.cse.ucsc.edu + Allow from hgw3.cse.ucsc.edu + Allow from hgw4.cse.ucsc.edu + Allow from hgw5.cse.ucsc.edu + Allow from hgw6.cse.ucsc.edu + Allow from hgw7.cse.ucsc.edu + Allow from hgw8.cse.ucsc.edu + +``` + +**PLEASE NOTE that this introduces a security hole** , the impact of which depends on whether you have restricted access +to the dataset via Galaxy's [internal dataset permissions](https://galaxyproject.org/learn/security-features/). + +- By default, data in Galaxy is public. Normally with a Galaxy server behind authentication in a proxy server this is of + little concern since only clients who've authenticated can access Galaxy. However, if display site exceptions are made + as shown above, anyone could use those public sites to bypass authentication and view any **public** dataset on your + Galaxy server. If you have not changed from the default and most of your datasets are public, you should consider + running your own display sites that are also behind authentication rather than using the public ones. + +- For datasets for which access has been restricted to one or more roles (i.e. it is no longer "public"), access for + reading via external browsers is only allowed for a brief period, when someone with access permission clicks the + "display at..." link. During this period, anyone who has the dataset ID would then be able to use the browser to view + this dataset. Although such a scenario is unlikely, it is technically possible. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 032064a6ac9..e667df8cabe 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -11,6 +11,7 @@ This documentation is in the midst of being ported and unified based on resource production scaling nginx + apache cluster jobs tool_panel diff --git a/doc/source/admin/nginx.md b/doc/source/admin/nginx.md index 2c71c679c51..d93b7533b58 100644 --- a/doc/source/admin/nginx.md +++ b/doc/source/admin/nginx.md @@ -5,10 +5,6 @@ Galaxy sites ([Main](https://galaxyproject.org/main/) and [Test](https://galaxyp [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. -```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. -``` ## Prerequisites @@ -25,6 +21,11 @@ For the purposes of this example, we assume that: Throughout the configuration examples in this document, in order to avoid reptition, `#...` 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. +``` + ## Basic Configuration The use of SSL is **strongly encouraged** to avoid exposure of confidential information such as datasets and user @@ -313,7 +314,7 @@ previous section: Galaxy sends files (e.g. dataset downloads) by opening the file and streaming it in chunks through the proxy server. However, this ties up the Galaxy process, which can impact the performance of other operations (see [Production Server -Configuration](/src/admin/config/performance/production-server/index.md) for a more in-depth explanation). +Configuration](production.html) for a more in-depth explanation). Nginx can assume this task instead and as an added benefit, speed up downloads. This is accomplished through the use of the special `X-Accel-Redirect` header. Dataset security is maintained in this configuration because nginx will still @@ -459,4 +460,4 @@ To secure this page to only Galaxy administrators, adjust your nginx config acco ### External User Authentication - [Nginx for External Authentication](https://galaxyproject.org/admin/config/nginx-external-user-auth/) -- [Built-in Galaxy External Authentication](../authentication.html) +- [Built-in Galaxy External Authentication](authentication.html) diff --git a/doc/source/admin/production.md b/doc/source/admin/production.md index ae6310f25ce..9d18219c850 100644 --- a/doc/source/admin/production.md +++ b/doc/source/admin/production.md @@ -95,7 +95,7 @@ Downloading and uploading data can also be moved to the proxy server. This is e Virtually any server that proxies HTTP should work, although we provide configuration examples for: -* [Apache](special_topics/apache.html), and +* [Apache](apache.html), and * [nginx](nginx.html), a high performance reverse proxy, used by our public Galaxy sites ### Using a compute cluster @@ -163,4 +163,4 @@ Finally, if you are using Galaxy <= release_2014.06.02, we recommend that you in ### Make the proxy handle uploads and downloads -By default, Galaxy receives file uploads as a stream from the proxy server and then writes this file to disk. Likewise, it sends files as a stream to the proxy server. This occupies the GIL in that Galaxy process and will decrease responsiveness for other operations in that process. To solve this problem, you can configure your proxy server to serve downloads directly, involving Galaxy only for the task of authorizing that the user has permission to read the dataset. If using nginx as the proxy, you can configure it to receive uploaded files and write them to disk itself, only notifying Galaxy of the upload once it's completed. All the details on how to configure these can be found on the [Apache](special_topics/apache.html) and [nginx](nginx.html) proxy instruction pages. +By default, Galaxy receives file uploads as a stream from the proxy server and then writes this file to disk. Likewise, it sends files as a stream to the proxy server. This occupies the GIL in that Galaxy process and will decrease responsiveness for other operations in that process. To solve this problem, you can configure your proxy server to serve downloads directly, involving Galaxy only for the task of authorizing that the user has permission to read the dataset. If using nginx as the proxy, you can configure it to receive uploaded files and write them to disk itself, only notifying Galaxy of the upload once it's completed. All the details on how to configure these can be found on the [Apache](apache.html) and [nginx](nginx.html) proxy instruction pages. diff --git a/doc/source/admin/scaling.md b/doc/source/admin/scaling.md index 02c40562ee9..8829f18ff90 100644 --- a/doc/source/admin/scaling.md +++ b/doc/source/admin/scaling.md @@ -66,7 +66,7 @@ roles (serving static content, serving dataset downloads, etc.) as described in configuration](production.html) documentation. When using uWSGI with a proxy server, it is recommended that you use the native high performance uWSGI protocol -(supported by both [Apache](special_topics/apache.html) and [nginx](nginx.html)) between uWSGI and the +(supported by both [Apache](apache.html) and [nginx](nginx.html)) between uWSGI and the proxy server, rather than HTTP. ### uWSGI with jobs handled by web workers (default configuration) @@ -248,7 +248,7 @@ permission on the socket. Because Galaxy and the proxy server most likely run as be the case by default. One common solution is to add the proxy server's user to the Galaxy user's primary group. uWSGI's `chmod-socket` option can also help here. -You can consult the Galaxy documentation for [Apache](special_topics/apache.html) or [nginx](nginx.html) +You can consult the Galaxy documentation for [Apache](apache.html) or [nginx](nginx.html) for help with the proxy-side configuration. By setting the `socket` option, `run.sh` will no longer automatically serve Galaxy via HTTP (since it is assumed that diff --git a/doc/source/admin/special_topics/apache.md b/doc/source/admin/special_topics/apache.md deleted file mode 100644 index 8e9fe6c8f29..00000000000 --- a/doc/source/admin/special_topics/apache.md +++ /dev/null @@ -1,228 +0,0 @@ -# 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. - -Currently the only recommended way to run Galaxy with Apache is using `mod_rewrite` and `mod_proxy`. Either `mod_proxy_uwsgi` or `mod_proxy_http` may be used from there. - -To support proxying, the `mod_proxy`, `mod_http_proxy` and `mod_rewrite` modules must be enabled in the Apache config. The main proxy directives, `ProxyRequests` and `ProxyVia` do **not** need to be enabled. - -## 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 -.. 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. -``` - -## Basic configuration - -### Allow Encoded Slashes in URLs - -Some Galaxy URLs contain encoded slashes (%2F) in the path and Apache will not serve these URLs by default. To configure Apache to serve URLs with encoded slashes in the path, add the following line to your Apache configuration file: - -```apache -AllowEncodedSlashes NoDecode -``` - -**Note**: The `NoDecode` setting was added in httpd 2.2.18, and CentOS 6 (as RHEL 6 does) only has 2.2.15. The [CentOS SCLo SIG Repo](https://wiki.centos.org/SpecialInterestGroup/SCLo/CollectionsList) has an httpd24 package. - -### Serving Galaxy at the web server root (/) - -For a default Galaxy configuration running on [http://localhost:8080/](http://localhost:8080/), the following lines in the Apache configuration will proxy requests to the Galaxy application: - -```apache -# Rewrite -RewriteEngine on -RewriteRule ^(.*) http://localhost:8080$1 [P] -``` - -Or, if using `mod_proxy` with HTTP transport - -```apache -ProxyPass / http://127.0.0.1:8080/ -``` - -Or, if using `mod_proxy` with uWSGI transport - -```apache -ProxyPass / uwsgi://127.0.0.1:4001/ -``` - -Thus, all requests on your server are now redirected to Galaxy. Because this example uses the "root" of your web server, you may want to use a [VirtualHost](http://httpd.apache.org/docs/2.2/vhosts/) to be able to run other sites from this same server. - -If your Apache server is set up to use `mod_security`, you may need to modify the value of the `SecRequestBodyLimit`. The default value on some systems will limit uploads to only a few kilobytes. - -Since Apache is more efficient 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. To do so, your configuration will now include the following, where `$GALAXY_ROOT` should be replaced with the filesystem path to your Galaxy installation - -```apache -RewriteEngine on -RewriteRule ^/static/style/(.*) $GALAXY_ROOT/static/june_2007_style/blue/$1 [L] -RewriteRule ^/static/scripts/(.*) $GALAXY_ROOT/static/scripts/packed/$1 [L] -RewriteRule ^/static/(.*) $GALAXY_ROOT/static/$1 [L] -RewriteRule ^/favicon.ico $GALAXY_ROOT/static/favicon.ico [L] -RewriteRule ^/robots.txt $GALAXY_ROOT/static/robots.txt [L] -``` - -You will need to ensure that filesystem permissions are set such that the user running your Apache server has access to the Galaxy static/ directory. - -### Serving Galaxy at a sub directory (such as /galaxy) - -It may be necessary to house Galaxy at an address other than the web server root (`http://www.example.org/galaxy`), instead of `http://www.example.org`). To do this, you need to make the following changes: - -Two changes are necessary: - -1. In the apache config, prefix all of the location directives with your prefix, like so: - -```apache -RewriteEngine on -RewriteRule ^/galaxy/static/style/(.*) $GALAXY_ROOT/static/june_2007_style/blue/$1 [L] -RewriteRule ^/galaxy/static/scripts/(.*) $GALAXY_ROOT/static/scripts/packed/$1 [L] -RewriteRule ^/galaxy/static/(.*) $GALAXY_ROOT/static/$1 [L] -RewriteRule ^/galaxy/favicon.ico $GALAXY_ROOT/static/favicon.ico [L] -RewriteRule ^/galaxy/robots.txt $GALAXY_ROOT/static/robots.txt [L] -``` - -Note the first rewrite rule deals with the missing trailing slash problem. If left out, [http://www.example.org/galaxy](http://www.example.org/galaxy) will result in a 404 error. - -If you are using `mod_rewrite` for serving: - -``` -RewriteRule ^/galaxy$ /galaxy/ [R] -RewriteRule ^/galaxy(.*) http://localhost:8080$1 [P] -``` - -Or for `proxy_http`/`proxy_uwsgi`: - -``` -ProxyPass /galaxy http://127.0.0.1:8080/galaxy -# or -ProxyPass /galaxy uwsgi://127.0.0.1:4001/ -``` - -2. The Galaxy application needs to be aware that it is running with a prefix (for generating URLs in dynamic pages). This is accomplished by configuring a Paste proxy-prefix filter in the `[app:main]` section of `config/galaxy.ini` and restarting Galaxy: - - -```ini -[filter:proxy-prefix] -use = egg:PasteDeploy#prefix -prefix = /galaxy - -[app:main] -filter-with = proxy-prefix -cookie_path = /galaxy -``` - -`cookie_prefix` should be set to prevent Galaxy's session cookies from clobbering each other if running more than one instance of Galaxy in different subdirectories on the same hostname. - -### SSL - -If you place Galaxy behind a proxy address that uses SSL (i.e., `https://` URLs), edit your galaxy location block (e.g. `location /` when served at the root, or something else like `location /galaxy` when served under a prefix) - -```apache - - ... - RequestHeader set X-URL-SCHEME https - ... - -``` - -Setting `X-URL-SCHEME` makes Galaxy aware of what type of URL it should generate for external sites like Biomart. This should be added to the existing `` block if you already have one, and adjusted accordingly if you're serving Galaxy from a subdirectory. - -## Advanced Configuration Topics - -### Compression and caching - -All of Galaxy's static content can be cached on the client side, and everything (including dynamic content) can be compressed on the fly. This will decrease download and page load times for your clients, as well as decrease server load and bandwidth usage. To enable, you'll need to load `mod_deflate` and `mod_expires` in your Apache configuration, and then set: - -```apache - - ... - # Compress all uncompressed content. - SetOutputFilter DEFLATE - SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-gzip dont-vary - SetEnvIfNoCase Request_URI \.(?:t?gz|zip|bz2)$ no-gzip dont-vary - SetEnvIfNoCase Request_URI /history/export_archive no-gzip dont-vary - - - # Allow browsers to cache everything from /static for 6 hours - ExpiresActive On - ExpiresDefault "access plus 6 hours" - ... - -``` - -The contents above should be added to the existing `` block if you already have one, and adjusted accordingly if you're serving Galaxy from a subdirectory. - -### Sending files using Apache - -Galaxy sends files (e.g. dataset downloads) by opening the file and streaming it in chunks through the proxy server. However, this ties up the Galaxy process, which can impact the performance of other operations (see [production configuration](../production.html) for a more in-depth explanation). - -Apache can assume this task instead and as an added benefit, speed up downloads. This is accomplished through the use of `mod_xsendfile`, a 3rd-party Apache module. Dataset security is maintained in this configuration because Apache will 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 OS's repositories. Once done, add the appropriate `LoadModule` directive to your Apache configuration to load the xsendfile module and the `XSendFile` directives to your proxy configuration: - -```apache - - XSendFile on - XSendFilePath / - -``` - -Finally edit your `$GALAXY_ROOT/config/galaxy.yml` and make the following change before restarting Galaxy: - -```yaml -galaxy: - # ... - apache_xsendfile: true -``` - -For this to work, the user under which your nginx server runs will need read access to Galaxy's `$GALAXY_ROOT/database/files/` directory and its contents. - -### External user authentication - -- [Apache for External Authentication](https://galaxyproject.org/admin/config/apache-external-user-auth/) -- [Built-in Galaxy External Authentication](../authentication.html) - -### Display Sites - -Display sites such as UCSC work not by sending data directly from Galaxy to UCSC via the client's browser, but by sending UCSC a URL to the data in Galaxy that the UCSC server will retrieve data from. Since enabling authentication will place **all** of Galaxy behind authentication, such display sites will no longer be able to access data via that URL. If `display_servers` is set to a non-empty value in `$GALAXY_ROOT/config/galaxy.yml`, this tells Galaxy it should allow the named servers access to data in Galaxy. However, you still need to configure Apache to allow access to the datasets. An example config is provided here that allows the UCSC Main/Test backends: - -```apache - - Satisfy Any - Order deny,allow - Deny from all - Allow from hgw1.cse.ucsc.edu - Allow from hgw2.cse.ucsc.edu - Allow from hgw3.cse.ucsc.edu - Allow from hgw4.cse.ucsc.edu - Allow from hgw5.cse.ucsc.edu - Allow from hgw6.cse.ucsc.edu - Allow from hgw7.cse.ucsc.edu - Allow from hgw8.cse.ucsc.edu - -``` - -**PLEASE NOTE that this introduces a security hole** , the impact of which depends on whether you have restricted access to the dataset via Galaxy's [internal dataset permissions](https://galaxyproject.org/learn/security-features/). - -- By default, data in Galaxy is public. Normally with a Galaxy server behind authentication in a proxy server this is of little concern since only clients who've authenticated can access Galaxy. However, if display site exceptions are made as shown above, anyone could use those public sites to bypass authentication and view any **public** dataset on your Galaxy server. If you have not changed from the default and most of your datasets are public, you should consider running your own display sites that are also behind authentication rather than using the public ones. - -- For datasets for which access has been restricted to one or more roles (i.e. it is no longer "public"), access for reading via external browsers is only allowed for a brief period, when someone with access permission clicks the "display at..." link. During this period, anyone who has the dataset ID would then be able to use the browser to view this dataset. Although such a scenario is unlikely, it is technically possible. - - -### Proxying multiple galaxy worker threads - -If you've configured multiple threads for galaxy in the `config/galaxy.yml` file, you will need a `ProxyBalancer` to manage sending requests to each of the threads. You can do that with apache configuration as follows: - -```apache - - BalancerMember http://localhost:8400 - BalancerMember http://localhost:8401 - - - -# Replace the following line from the regular proxy configuration: -# RewriteRule ^(.*) http://localhost:8080$1 [P] -# With: -RewriteRule ^(.*) balancer://galaxy$1 [P] -``` diff --git a/doc/source/admin/special_topics/index.rst b/doc/source/admin/special_topics/index.rst index 507e2b4cffe..f069300e744 100644 --- a/doc/source/admin/special_topics/index.rst +++ b/doc/source/admin/special_topics/index.rst @@ -5,7 +5,6 @@ Special Topics .. toctree:: :maxdepth: 2 - apache ftp interactive_environments mulled_containers diff --git a/lib/galaxy/webapps/galaxy/api/configuration.py b/lib/galaxy/webapps/galaxy/api/configuration.py index 25f4f8d9e96..d70b0e27da1 100644 --- a/lib/galaxy/webapps/galaxy/api/configuration.py +++ b/lib/galaxy/webapps/galaxy/api/configuration.py @@ -87,6 +87,9 @@ class ConfigurationController(BaseAPIController): @expose_api @require_admin def dynamic_tool_confs(self, trans): + # WARNING: If this method is ever changed so as not to require admin privileges, update the nginx proxy + # documentation, since this path is used as an authentication-by-proxy method for securing other paths on the + # server. A dedicated endpoint should probably be added to do that instead. confs = self.app.toolbox.dynamic_confs(include_migrated_tool_conf=True) return map(_tool_conf_to_dict, confs)