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/:

1. Edit $NEXUS_HOME/conf/nexus.properties. Change nexus-webapp-context-path=/nexus to nexus-webapp-context-path=/
2. Restart the repository manager and verify that it is available on http://localhost:8081/ and no longer available at http://localhost:8081/nexus/.
3. 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

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";
        }
    }
}