Skip to main content

Run Behind a Reverse Proxy

Using a reverse proxy in front of Nexus Repository is a highly recommended and common practice for several compelling reasons, covering security, performance, flexibility, and operational efficiency. This section provides guidance on how to configure a reverse proxy servers to work with Nexus Repository.

Here are some of the key benefits:

  • SSL/TLS Termination (HTTPS Access)

    Nexus Repository may be configured with SSL, but offloading this to a reverse proxy like Nginx or Apache is often preferred. The reverse proxy handles the SSL handshake, decrypts incoming requests, and encrypts outgoing responses.

    Using a reverse proxy to resolve SSL (Secure Sockets Layer) is a common and highly recommended practice, especially in production environments. It's often referred to as SSL/TLS Termination or SSL Offloading. Doing this offloads the CPU-intensive SSL processing from the Nexus Repository so that it's resources are focused on handling other requests.

    You only need to install and manage SSL certificates on the reverse proxy server, rather than on every individual Nexus Repository instance. This simplifies certificate renewal and the upgrade workflow for your server.

  • Enhanced Security

    The reverse proxy acts as a buffer between the public internet and your Nexus Repository instance. It can be placed in a Demilitarized Zone (DMZ), protecting your internal Nexus Repository server from direct exposure to external threats.

    In the instance where Nexus Repository needs to be proxied at a different base path you must change the default path by editing a property value.

    See Base URL Capability

  • Standardization

    A reverse proxy allows you to expose Nexus on standard HTTP (80) and HTTPS (443) ports, simplifying access for clients and adhering to network policies. This is useful for Docker repositories, which require specific ports or subdomains for push/pull operations if not proxied.

    See Docker Reverse Proxy Strategies

  • Load Balancing and High Availability

    In a high-availability setup (Nexus Repository Pro), a reverse proxy acts as a load balancer to distribute incoming requests across multiple instances, improving performance and ensuring continuous availability even when one node fails.

    See High-Availability Deployments

  • Single Sign-On

    When setting up SSO and using a reverse proxy instead of Nexus Repository, you need to forward to the same context path on the reverse proxy and the Nexus Repository instance for SSO host headers to be accepted.

    See Configuring the Runtime Environment

Tip

Consult your network administrator to ensure your configuration is secure.

Reverse Proxy on Restricted Ports

Forward requests from port 80 to the default Nexus Repository port 8081.

ProxyRequests Off
ProxyPreserveHost On
  
<VirtualHost *:80>
  ServerName www.example.com
  ServerAdmin admin@example.com

  AllowEncodedSlashes NoDecode

  ProxyTimeout 300
  ProxyPass / http://localhost:8081/ nocanon
  ProxyPassReverse / http://localhost:8081/
  ErrorLog logs/www.example.com/error.log
  CustomLog logs/www.example.com/access.log common
</VirtualHost>
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
    client_max_body_size 1G;
  
    # optimize downloading files larger than 1G
    #proxy_max_temp_file_size 2G;
  
    location / {
      # Use IPv4 upstream address instead of DNS name to avoid attempts by nginx to use IPv6 DNS lookup
      proxy_pass http://127.0.0.1:8081/;
      proxy_pass_header Server;
      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 and Custom Context Path

Accept requests from a custom subdomain (repo) and the application context path (/nexus).

ProxyRequests Off
ProxyPreserveHost On
  
<VirtualHost *:80>
  ServerName repo.example.com
  ServerAdmin admin@example.com

  AllowEncodedSlashes NoDecode

  ProxyTimeout 300
  ProxyPass /nexus http://localhost:8081/nexus nocanon
  ProxyPassReverse /nexus http://localhost:8081/nexus
  ErrorLog logs/repo.example.com/nexus/error.log
  CustomLog logs/repo.example.com/nexus/access.log common
</VirtualHost>
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
    client_max_body_size 1G;
  
    # optimize downloading files larger than 1G
    # proxy_max_temp_file_size 2G;
  
    location /nexus {
      # Use IPv4 upstream address instead of DNS name to avoid attempts by nginx to use IPv6 DNS lookup
      proxy_pass http://127.0.0.1:8081/nexus;
      proxy_pass_header Server;
      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

Accept HTTPS requests on the standard port 443 and serve content using the default non-restricted HTTP port 8081.

To test your configuration, review the steps to generate a self-signed SSL certificate for reverse proxy servers.

The example requires that Apache httpd is configured with the mod_SSL and mod_headers modules.

Listen 443
  
ProxyRequests Off
ProxyPreserveHost On
  
<VirtualHost *:443>
  SSLEngine on
  
  SSLCertificateFile "example.pem"
  SSLCertificateKeyFile "example.key"
  
  AllowEncodedSlashes NoDecode

  ServerName repo.example.com
  ServerAdmin admin@example.com


  ProxyTimeout 300
  ProxyPass / http://localhost:8081/ nocanon
  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>

The example assumes that nginx has been 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
    client_max_body_size 1G;
  
    # optimize downloading files larger than 1G
    #proxy_max_temp_file_size 2G;
  
    ssl on;
    ssl_certificate      example.pem;
    ssl_certificate_key  example.key;
  
    location / {
      # Use IPv4 upstream address instead of DNS name to avoid attempts by nginx to use IPv6 DNS lookup
      proxy_pass http://127.0.0.1:8081/;
      proxy_pass_header Server;
      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";
    }
  }
}

Apache httpd with npm Repositories

Npm scoped packages use encoded slash characters ("/") in their URL's. By default, Apache does not allow encoded slashes to pass through. When using npm and Apache reverse proxy add the following to your configuration to allow encoded slashes through:

AllowEncodedSlashes NoDecode

The ProxyPass directive needs the nocanon option:

ProxyPass / http://localhost:8081/ nocanon