Nginx reverse proxy for IBM Aspera Shares and Faspex 5

IBM Aspera Shares and Faspex can sit behind a common Nginx reverse proxy so users access both applications through a single HTTPS endpoint. Instead of publishing separate backend servers directly, Nginx receives the request on port 443 and sends it to the correct Aspera application based on the URL path.

The routing pattern is simple: the root path / goes to Aspera Shares, while /aspera/faspex goes to Faspex.

Version note. This guide is based on an Aspera Proxy Nginx configuration used for Shares and Faspex 5. IBM's current Aspera Proxy documentation supports Nginx reverse proxying for Faspex, Shares and Console. Validate product versions, TLS policy and application-specific settings against the IBM documentation for your environment.

What we are building

Nginx reverse proxy architecture showing users accessing a single HTTPS endpoint that routes root path to Aspera Shares and /aspera/faspex path to Faspex 5.

Both applications remain on their own backend systems. The Proxy becomes the public entry point and performs the routing.

Why use one reverse proxy?

Benefit	Why it matters
Single endpoint	Users remember one FQDN instead of separate Shares and Faspex addresses.
Central TLS	The public certificate is managed at one entry point.
Backend isolation	Shares and Faspex servers do not need to be directly exposed to users.
Path-based routing	Nginx sends each request to the correct Aspera application.
Simpler operations	Logging, access controls and future routing changes can be centralized.

Traffic flow

Request	Nginx location	Backend
`https://proxy.example.com/`	`location /`	`https://shares.example.com`
`https://proxy.example.com/aspera/faspex`	`location /aspera/faspex`	`https://faspex.example.com`

Nginx uses the more specific path when a request starts with /aspera/faspex. Everything else falls through to the root / location and is sent to Shares.

Prerequisites

Aspera Proxy / Nginx host. The server can reach both backend applications over HTTPS.
Shares backend. Shares is installed, running and accessible from the Proxy.
Faspex backend. Faspex 5 is installed, running and accessible from the Proxy.
DNS. A public or enterprise DNS record such as proxy.example.com points to the Proxy.
TLS certificate. A CA-signed certificate and private key are available for the Proxy FQDN.
Firewall. TCP 443 is allowed from users to the Proxy and from the Proxy to the HTTPS backends.

Step 1 — Verify both backends directly

Before adding Nginx, verify that the Proxy server can reach Shares and Faspex directly.

curl -kI https://shares.example.com
curl -kI https://faspex.example.com

You do not need the applications to return the same status code, but the HTTPS connection should reach the intended backend rather than failing at DNS, routing or TLS.

Step 2 — Prepare the Proxy certificate

The reference configuration stores the Proxy certificate and key under the Aspera Proxy directory:

/opt/aspera/proxy/etc/aspera_server_cert.pem
/opt/aspera/proxy/etc/aspera_server_key.pem

For production, use a certificate whose Subject Alternative Name includes the Proxy FQDN that users will access.

Step 3 — Configure Nginx

The supplied configuration uses one HTTPS server block and two location blocks. The sanitized version below keeps the same routing model while using placeholders suitable for a public example.

# Aspera configuration - reverse proxy for Faspex 5 + Shares

pid var/run/asperanginx.pid;

events {
  worker_connections 1024;
}

http {
  server {
    listen 443 ssl;
    server_name proxy.example.com;

    ssl_certificate     /opt/aspera/proxy/etc/aspera_server_cert.pem;
    ssl_certificate_key /opt/aspera/proxy/etc/aspera_server_key.pem;

    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 0;
    max_ranges 1;

    # Aspera Shares
    location / {
      proxy_pass https://shares.example.com;
    }

    # Faspex 5
    location /aspera/faspex {
      proxy_redirect off;
      proxy_pass https://faspex.example.com;

      proxy_set_header Host $http_host;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto https;
      proxy_set_header X-Real-IP $remote_addr;
    }
  }
}

TLS note. The supplied reference configuration used TLS 1.2 and an explicit cipher list. IBM's current Proxy documentation states that TLS 1.2 and TLS 1.3 can be used and recommends checking the ciphers supported by the installed Aspera OpenSSL build instead of assuming an old cipher list is still appropriate.

What each directive is doing

Directive	Purpose
`listen 443 ssl`	Publishes the common HTTPS entry point.
`server_name`	Defines the Proxy FQDN used by clients.
`ssl_certificate`	Identifies the certificate presented by the Proxy.
`client_max_body_size 0`	Removes the standard Nginx request-body size limit for this server block.
`location /`	Routes the default site to Aspera Shares.
`location /aspera/faspex`	Routes Faspex-specific URLs to the Faspex backend.
`proxy_set_header Host`	Preserves the public host information seen by the application.
`X-Forwarded-For`	Passes the original client IP chain to the backend.
`X-Forwarded-Proto`	Tells the backend that the original client connection used HTTPS.
`X-Real-IP`	Provides the backend with the immediate client IP seen by Nginx.

Step 4 — Make Faspex aware of the external address

Faspex generates links for users, email notifications and other application functions based on its configured external address. When an external reverse proxy is introduced, make sure Faspex recognizes the Proxy hostname or alternate address used by clients.

For Faspex 5, also remember that Faspex itself is containerized and has its own internal Nginx router. The Nginx in this blog sits in front of that Faspex router; it does not replace Faspex's internal routing layer.

Step 5 — Make Shares accept the Proxy hostname

If Shares validates the hostnames by which it can be referenced, add the Proxy hostname to the Shares accepted-host configuration for your version.

The idea is simple: if users browse to proxy.example.com, the Shares application must consider that hostname valid even though its own backend hostname may be different.

Step 6 — Validate the Nginx configuration

Before restarting the service, run Nginx's built-in syntax check.

/opt/aspera/nginx/nginx -t

A successful validation confirms that the configuration can be parsed. It does not yet prove that DNS, certificates or backend applications are reachable.

Step 7 — Restart Nginx

Restart the Aspera Nginx service using the service-management method used by your deployment.

systemctl restart asperanginx
systemctl status asperanginx

Then confirm that Nginx is listening on TCP 443.

ss -lntp | grep :443

Step 8 — Validate Shares through the Proxy

Open the root Proxy URL:

https://proxy.example.com/

The request should be served by the Shares backend. Verify login, navigation and any links that must return to the same external hostname.

Step 9 — Validate Faspex through the Proxy

IBM documents a Faspex health endpoint that is useful for validating reverse-proxy routing:

curl -ki https://proxy.example.com/aspera/faspex/health

A successful response shows that the Proxy received the request and routed the Faspex path to the Faspex application.

Then test the Faspex web interface through the Proxy and verify login, package workflows, external links and notification links used by your deployment.

One hostname, two applications

User-facing URL	Application
`https://proxy.example.com/`	Aspera Shares
`https://proxy.example.com/aspera/faspex`	Faspex 5

This is the main advantage of the design: users see one secure endpoint while the applications remain independently deployed behind it.

Production checklist

Use CA-signed TLS. The Proxy certificate should match the public FQDN.
Keep backends private. Allow Shares and Faspex HTTPS access from the Proxy and approved management networks rather than exposing them unnecessarily.
Use current TLS policy. IBM currently documents TLS 1.2 and 1.3 for Aspera Proxy Nginx; align ciphers with the installed OpenSSL version and enterprise policy.
Configure external hostnames. Faspex and Shares need to recognize the address users actually browse to.
Preserve client context. Forward the required Host and X-Forwarded headers when the application depends on them.
Test application-generated links. Login alone is not enough; validate email links, external submissions and redirects.
Monitor the Proxy. The shared Nginx endpoint is now a common dependency for both applications.

Troubleshooting

Shares opens but Faspex returns 404

Verify the specific location /aspera/faspex block exists and that the request is reaching the intended Faspex backend. Test the documented health endpoint through both the Proxy and directly against Faspex.

Faspex external links use the wrong hostname

Check the Faspex external address / alternate address configuration. The application must know the hostname presented by the external reverse proxy.

Faspex logs an Origin or base URL mismatch

IBM documents a potential issue with external Nginx and the Faspex 5 router where the Origin header does not match the application's calculated base URL. For affected versions, IBM recommends using proxy_set_header Host $host; instead of adding :$server_port to the Host header, then restarting both Nginx and Faspex.

Shares rejects the Proxy hostname

Verify the Proxy address is listed among the hostnames that Shares accepts for your installed version.

Nginx configuration is valid but the page does not open

Separate the test into layers:

Verify TCP 443 is listening on the Proxy.
Verify the Proxy resolves both backend hostnames.
Verify the Proxy can establish HTTPS connections to both backends.
Test Shares through /.
Test Faspex through /aspera/faspex/health.

Final take

Nginx path-based routing is a clean way to publish IBM Aspera Shares and Faspex behind one secure endpoint.

Root path: / → Shares.

Faspex path: /aspera/faspex → Faspex 5.

The configuration itself is small. The important production work is around TLS, backend reachability, forwarded headers, and making sure both applications understand the external Proxy hostname. Once those pieces are aligned, the Proxy becomes a simple and maintainable front door for both Aspera web applications.