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 is a lightweight HTTP server designed with high performance proxying in mind. The Galaxy Project’s public
servers, usegalaxy.org (“Main”) and Test, as well as the Docker Galaxy project use
NGINX, rather than Apache, to proxy Galaxy. NGINX was chosen for its simple, fast load balancing and other
proxy-oriented features.

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
nginx’s document root. By default, this would expose all of Galaxy (including datasets) to anyone on the web.

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 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 package contains all the necessary modules used in this guide. On EL, the EPEL
version of nginx is suitable.

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.

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 nginx and Galaxy, rather
than HTTP. Legacy instructions for proxying via HTTP can be found in the Galaxy Release 17.09 proxy documentation.

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.

uWSGI protocol support is built in to nginx, so (unlike Apache) no extra modules or recompiling should be required.

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. 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
documentation.

Be sure to set $galaxy_root to the path to your copy of Galaxy and modify the value of uwsgi_pass 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 documentation. If using a UNIX domain
socket, be sure to pay particular attention to the discussion of users and permissions.

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 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 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.

The parameter client_max_body_size specifies the maximum upload size that can be handled by POST requests through
nginx. You should set this to the largest file size that you wish to allow for upload and that could be reasonably
handled by your site. It defaults to 1MB, so it will need to be increased if you are dealing with genome sized
datasets.

If you must serve Galaxy without SSL, you would simply replace the listen directives in the SSL server{} block
with the listen directives from the non-SSL server{} block and remove the non-SSL block and SSL directives from
the http{} block.

If the proxy works but you are getting 404 errors for Galaxy’s static content, be sure that the user that nginx 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-uwww-datals/srv/galaxy/server/static.

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:

In the nginx config, prefix all of the location directives with your prefix and redirect requests from /prefix to
/prefix/ like so:

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:

uwsgi:#...socket:unix:///srv/galaxy/var/uwsgi.sockmount:/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 documentation, other options unrelated to proxying
should also be set in the uwsgi section of the config.

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 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
check with Galaxy to ensure that the requesting user has permission to access the dataset before sending it.

To enable it, add the following to your Galaxy’s server{} block:

location/_x_accel_redirect/{internal;alias/;}

Next, edit galaxy.yml and make the following change before restarting Galaxy:

galaxy:#...nginx_x_accel_redirect_base:'/_x_accel_redirect'

For this to work, the user under which your nginx 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 nginx 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:

Galaxy receives files (e.g. dataset uploads) by streaming them in chunks through the proxy server and writing the files
to disk. However, this again ties up the Galaxy process. nginx can assume this task instead and as an added benefit,
speed up uploads. This is accomplished through the use of
nginx_upload_module, a 3rd-party nginx module.

To enable it, you must first download, compile and install nginx with the upload module, since prior to NGINX 1.11.5,
nginx did not support shared modules, and the upload module is not yet shared-compatible. Because this is a tedious
and complicated process, the Galaxy Committers team maintains (for some platforms) versions of nginx modified from their
upstream package sources (APT, EPEL, etc.) to include the upload module:

To contribute support for additional platforms, please see the Galaxy
Starforge project, which is used to do the repackaging.

Once nginx with the upload module is installed, create a directory in which to store uploads (ideally, for performance
reasons, on the same filesystem as Galaxy’s datasets) and add the necessary directives to nginx.conf:

Note the user directive at the top, outside of the http{} block. To ensure that Galaxy has write permission on the
uploaded files, nginx’s workers will need to run as the same user as Galaxy.

When serving Galaxy at a URL prefix as described in the Serving Galaxy at a URL
prefix section, you will need to change set$dst/api/tools; to set$dst/prefix/api/tools; (e.g. set$dst/galaxy/api/tools;).

Finally, edit galaxy.yml and make the following change before restarting Galaxy:

After succesfully following the blog post, Galaxy reports should be available at e.g. https://galaxy.example.org/reports.
To secure this page to only Galaxy administrators, adjust your nginx config accordingly:

TODO: This is not valid for the uWSGI proxy method and needs to be updated. -nate 2018-01-11

location/reports{#...satisfyany;# only one auth method needs to succeeddenyall;# host-based auth is not allowedauth_request/_auth;# forward authentication}location/_auth{#internal; probably?# The used galaxy api endpoint is only available to galaxy admins and thus limits the access# to only logged in admins.proxy_passhttp://localhost/api/configuration/dynamic_tool_confs;proxy_pass_request_bodyoff;proxy_set_headerContent-Length"";proxy_set_headerX-Original-URI$request_uri;}