Repository Management with Nexus

Share

3.8. Running Nexus Behind a Reverse Proxy

Nexus is a sophisticated web application, answering HTTP requests using the high-performance servlet container Eclipse Jetty.

Organizations are sometimes required to run applications like Nexus 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. Always consult your reverse proxy administrator to ensure you configuration is secure.

There are two main settings of Nexus which can affect how reverse proxies interact.

3.8.1. Nexus Webapp Context Path

Nexus webapp context path is /nexus by default. This means every URL path used to access Nexus must begin with /nexus.

In cases where Nexus 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 Nexus at path slash ( / ) instead of /nexus/:

  1. Edit $NEXUS_HOME/conf/nexus.properties. Change nexus-webapp-context-path=/nexus to nexus-webapp-context-path=/
  2. Restart Nexus and verify that it is available on http://localhost:8081/ and no longer available at http://localhost:8081/nexus/.
  3. Emails triggered by your Nexus instance may include absolute links back to the originating Nexus server. As a matter of courtesy, set the Base URL in Nexus 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/.

3.8.2. Do Not Force Base URL

At AdministrationServerApplication Server Settings Nexus has a deprecated 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 Nexus acts like it is being accessed at the value of base URL.

[Warning]

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 Nexus to not work properly through a reverse proxy.

3.8.3. Example: Reverse Proxy On Restricted Ports

Scenario: You need to expose Nexus on restricted port 80. Nexus should not be run with the root user. Instead run your reverse proxy on the restricted port 80 and Nexus on the default port 8081. End users will access Nexus using the virtual host URL http://www.example.com/nexus instead of http://localhost:8081/nexus.

Ensure your external host name ( 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;
    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;
        }
    }
}

3.8.4. Example: Reverse Proxy Virtual Host at Base Path

Scenario: You need to expose Nexus 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 Nexus 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;
    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;
        }
    }
}

3.8.5. Example: 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 Nexus 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 Nexus 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.

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;
    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";
        }
    }
}
[Note]

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 )