Running Behind a Reverse Proxy
Why Use a Reverse Proxy
Nexus Repository Manager is a sophisticated server application with a web-application user interface, answering HTTP requests using the high-performance servlet container Eclipse Jetty. Organizations are sometimes required to run applications like Nexus Repository Manager Pro or Nexus Repository Manager OSS behind a reverse proxy. Reasoning can include:
- security and auditing concerns
- network administrator familiarity
- organizational policy
- disparate application consolidation
- virtual hosting
- exposing applications on restricted ports
- SSL termination
We provide some general guidance on how to configure common reverse proxy servers to work with Nexus Repository Manager Pro and Nexus Repository Manager OSS. Always consult your reverse proxy administrator to ensure you configuration is secure.
Repository Manager Configuration
There are two main settings within repository manager which can affect how reverse proxies interact with it.
Webapp Context Path
The repository manager webapp context path is /nexus by default. This means every URL path used to access the repository manager must begin with /nexus.
In cases where the repository manager needs to be accessed at a different base path, through your reverse proxy or directly, you must change the default path by editing a property value.
For example, to expose the repository manager in the root context ( / ) instead of /nexus/:
- Edit
$NEXUS_HOME/conf/nexus.properties. Changenexus-webapp-context-path=/nexustonexus-webapp-context-path=/ - Restart the repository manager and verify that it is available on
http://localhost:8081/and no longer available athttp://localhost:8081/nexus/. - Emails triggered by your repository manager may include absolute links back to the originating server. As a matter of courtesy, set the Base URL as shown in Figure 6.4, “Administration Application Server Settings” under Application Server Settings to the URL that will be externally available to your users e.g.
http://repo.example.com/.
Do Not Force Base URL
Do not enable the Figure 6.4, “Administration Application Server Settings” Force Base URL unless explicitly advised by Sonatype - enabling this will most likely cause your repository manager to not work properly through a reverse proxy.
The Administration → Server → Application Server Settings configuration to Force Base URL feature. The original use case for forcing base URL is no longer valid.
When enabled, the incoming request host and base path is ignored and the repository manager acts like it is being accessed at the value of base URL.
Example Reverse Proxy Configuration
Reverse Proxy On Restricted Ports
Scenario: You need to expose the repository manager on restricted port 80. The repository manager should not be run with the root user. Instead run your reverse proxy on the restricted port 80 and the repository manager on the default port 8081. End users will access the repository manager using the virtual host URL http://www.example.com/nexus instead of http://localhost:8081/nexus.
Ensure your external host name (in this example: www.example.com) routes to your reverse proxy server.
Apache httpd
ProxyRequests Off ProxyPreserveHost On <VirtualHost *:80> ServerName www.example.com ServerAdmin admin@example.com ProxyPass /nexus http://localhost:8081/nexus ProxyPassReverse /nexus http://localhost:8081/nexus ErrorLog logs/www.example.com/nexus/error.log CustomLog logs/www.example.com/nexus/access.log common </VirtualHost>
nginx
http {
proxy_send_timeout 120;
proxy_read_timeout 300;
proxy_buffering off;
proxy_request_buffering off;
keepalive_timeout 5 5;
tcp_nodelay on;
server {
listen *:80;
server_name www.example.com;
# allow large uploads of files - refer to nginx documentation
client_max_body_size 1G;
# optimize downloading files larger than 1G - refer to nginx doc before adjusting
#proxy_max_temp_file_size 2G;
location /nexus {
proxy_pass http://localhost:8081/nexus;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
}Reverse Proxy Virtual Host at Base Path
Scenario: You need to expose the repository manager using a custom host name of repo.example.com on a restricted port at a base path of slash ( / ).
Ensure your external host name ( repo.example.com ) routes to your reverse proxy server and edit the webapp path to be slash ( / ).
Apache httpd
ProxyRequests Off ProxyPreserveHost On <VirtualHost *:80> ServerName repo.example.com ServerAdmin admin@example.com ProxyPass / http://localhost:8081/ ProxyPassReverse / http://localhost:8081/ ErrorLog logs/repo.example.com/nexus/error.log CustomLog logs/repo.example.com/nexus/access.log common </VirtualHost>
nginx
http {
proxy_send_timeout 120;
proxy_read_timeout 300;
proxy_buffering off;
proxy_request_buffering off;
keepalive_timeout 5 5;
tcp_nodelay on;
server {
listen *:80;
server_name repo.example.com;
# allow large uploads of files - refer to nginx documentation
client_max_body_size 1G;
# optimize downloading files larger than 1G - refer to nginx doc before adjusting
#proxy_max_temp_file_size 2G;
location / {
proxy_pass http://localhost:8081/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
}Reverse Proxy SSL Termination at Base Path
Scenario: Your organization has standardized on a reverse proxy to handle SSL certificates and termination. The reverse proxy virtual host will accept HTTPS requests on the standard port 443 and serve content from the repository manager running on the default non-restricted HTTP port 8081 transparently to end users.
Ensure your external host name ( repo.example.com ) routes to your reverse proxy server and edit the webapp path to be slash ( / ).
To test your configuration, we offer a quick reference on how to generate self-signed SSL certificates for reverse proxy servers.
Apache httpd
Ensure Apache httpd is loading mod_ssl and mod_headers.
Listen 443 ProxyRequests Off ProxyPreserveHost On <VirtualHost *:443> SSLEngine on SSLCertificateFile "example.pem" SSLCertificateKeyFile "example.key" ServerName repo.example.com ServerAdmin admin@example.com ProxyPass / http://localhost:8081/ ProxyPassReverse / http://localhost:8081/ RequestHeader set X-Forwarded-Proto "https" ErrorLog logs/repo.example.com/nexus/error.log CustomLog logs/repo.example.com/nexus/access.log common </VirtualHost>
nginx
Make sure nginx is compiled using the --with-http_ssl_module option.
http {
proxy_send_timeout 120;
proxy_read_timeout 300;
proxy_buffering off;
proxy_request_buffering off;
keepalive_timeout 5 5;
tcp_nodelay on;
server {
listen *:443;
server_name repo.example.com;
# allow large uploads of files - refer to nginx documentation
client_max_body_size 1G;
# optimize downloading files larger than 1G - refer to nginx doc before adjusting
#proxy_max_temp_file_size 2G;
ssl on;
ssl_certificate example.pem;
ssl_certificate_key example.key;
location / {
proxy_pass http://localhost:8081/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto "https";
}
}
}Reverse proxy configuration is going to vary and can get complex. Always consult the specific reverse proxy product documentation. Apache httpd ( mod_proxy , mod_ssl ), nginx ( ngx_http_proxy_module , ssl compatibility )