TLS, Reverse Proxies, Context Paths, HTTP Settings, Network Boundaries, and Secure Exposure: Concepts, Architecture, and Mental Model

1. The practical problem: the repository must not be the edge by accident

A Nexus Repository server can be perfectly configured at the repository layer and still be insecure or unreliable at the network layer. A developer may type one URL, but that request can cross DNS, a load balancer, a reverse proxy, TLS termination, a firewall boundary, and finally the Nexus listener. If any layer disagrees about scheme, host, port, or path, the symptom often appears inside a package manager as an authentication error, redirect loop, 404, certificate failure, or broken registry login.

The design goal is therefore not “turn on HTTPS.” It is to make each responsibility explicit. The edge owns public naming and usually TLS; the private Nexus listener serves the application; forwarded headers carry the original request identity; the context path tells Nexus where its application actually lives; repository paths identify content; and firewall rules prevent clients from bypassing the intended edge.

2. Request flow: seven objects, not one URL

flowchart TD
C[Client] --> D[DNS / local resolution]
D --> E[TLS reverse proxy :443 or lab :8443]
E -->|Host + X-Forwarded-*| N[Nexus listener 127.0.0.1:8081]
N --> R[Repository router / authorization]
R --> M[Database metadata]
R --> B[Blob content]
N --> L[request.log / nexus.log]
E -. certificate + SAN .-> C

The client resolves a name first. The TLS endpoint proves that name with a certificate whose Subject Alternative Name (SAN) contains the hostname. The reverse proxy terminates or re-encrypts TLS and forwards the request to Nexus. Nexus then applies its own application context, repository routing, authentication and authorization. Only after those checks does repository metadata or blob content participate.

The arrows are intentionally directional. A reverse proxy does not replace Nexus authorization, and a repository path does not configure TLS. The database does not store the certificate used by an external NGINX instance. The blob store does not decide whether X-Forwarded-Proto is correct.

3. Define the network objects before configuring them

4. Host and forwarded headers carry the original request identity

A proxy creates a second HTTP connection, so the backend can otherwise see only the proxy-to-Nexus connection. Host identifies the externally requested host when preserved. X-Forwarded-Proto tells Nexus whether the original client used HTTPS. X-Forwarded-Host can preserve the original host/port, and X-Forwarded-For records the client/proxy chain.

# Production-shaped NGINX fragment; use repo.example.invalid as documentation only.
location / {
    proxy_pass http://127.0.0.1:8081;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_request_buffering off;
}

Current Sonatype guidance says to keep the HTTP Forwarded Headers capability enabled when Nexus runs behind a reverse proxy. Disabling it means Nexus will not use the proxy-supplied forwarded headers to attribute request origin.

5. TLS identity is hostname identity

A TLS certificate is not merely encryption material. The client checks whether it trusts the issuer and whether the hostname it requested appears in the certificate SAN set. A certificate for nexus.lab.test does not become valid for 127.0.0.1 just because both reach the same process.

For production, certificates normally come from an organizational or public CA and rotate automatically. For a disposable loopback lab, a short-lived synthetic certificate is acceptable if the client explicitly trusts only that certificate or its lab CA. Never teach clients to normalize -k, --insecure, or globally disabled certificate verification as the fix for TLS errors.

6. Context path is application configuration, not a proxy illusion

Current runtime documentation places custom settings in $data-dir/etc/nexus.properties, not the install-directory defaults. The Nexus application context defaults to /. A real custom context can be configured with nexus-context-path=/nexus.

# $data-dir/etc/nexus.properties — disposable instance only
application-port=8081
application-host=127.0.0.1
nexus-context-path=/nexus

If Nexus itself is configured for /nexus, a reverse proxy must forward a compatible path. Sonatype specifically calls out same-context forwarding when SSO is involved. Do not expose /nexus externally while silently stripping it to a root-context Nexus and then assume every client, redirect, and authentication flow will infer the translation.

7. Registry endpoints add another routing layer

OCI/Docker clients speak a registry protocol centered on /v2/, not the normal browser navigation model. Current Nexus supports path-based routing for OCI in all deployments, self-hosted port connectors, and Pro-only subdomain routing. Port connectors reserve listener resources; Sonatype recommends reverse-proxy-managed SSL rather than managing certificates separately on many repository connectors.

flowchart TB
P[repo.example.invalid:443] --> UI[/UI and REST API/]
P --> RAW[/repository/raw-hosted/.../]
P --> OCI[/OCI path routing / repository-name / image/]
UI --> N[Nexus private listener]
RAW --> N
OCI --> N

The diagram does not mean all package formats use identical paths. It means the network edge can standardize the TLS boundary while Nexus still preserves format-specific protocol semantics behind it.

8. Read-only inspection before mutation

Capture evidence before changing listener or proxy settings. On a local archive installation, inspect the actual runtime and data-directory properties. Do not modify nexus-default.properties; current documentation says custom configuration belongs in the data directory.

# POSIX/Bash — read-only evidence
curl -fsS http://127.0.0.1:8081/service/rest/v1/status
printf '
Listener evidence:
'
ss -ltn 2>/dev/null | grep ':8081' || netstat -an | grep '8081'
printf '
Configured overrides:
'
grep -E '^(application-host|application-port|nexus-context-path)=' "$NEXUS_DATA/etc/nexus.properties" 2>/dev/null || true
printf '
Recent request evidence:
'
tail -n 20 "$NEXUS_DATA/log/request.log" 2>/dev/null || true

Also inspect Settings → System → Capabilities for HTTP Forwarded Headers and Base URL state, and Settings → Repositories for the exact client-facing repository names. These observations establish whether a later symptom came from a network change or from repository state that already existed.

9. State boundaries that must remain separate

10. Common wrong mental models

• “HTTPS means the backend can be public.” TLS protects transport; a private listener prevents edge bypass.
• “Base URL rewrites all traffic.” It is not a substitute for listener, context-path, and proxy routing.
• “The proxy can invent any prefix.” Nexus must understand its configured context path.
• “Use -k until the certificate works.” That removes the property the test is meant to prove.
• “Docker is just another browser path.” OCI/Docker routing and bearer-token behavior are format-specific.

11. Knowledge check

12. Summary and next step

A secure Nexus URL is a composition of DNS name, certificate identity, reverse-proxy policy, forwarded request metadata, private Nexus listener, context path, repository route, and Nexus authorization. Lesson 2 turns that model into a disposable loopback-only TLS lab and proves each boundary with evidence.

Official references and version notes

• Sonatype: Run Behind a Reverse Proxy — reverse-proxy benefits, forwarded-header requirement, SSL termination, context-path examples.
• Sonatype: Configuring the Runtime Environment — application port, data-directory overrides, and nexus-context-path.
• Sonatype: Configuring SSL — direct Jetty HTTPS and recommendation to use a reverse proxy when appropriate.
• Sonatype: Docker Registry — path and port routing plus reverse-proxy SSL recommendation.
• Sonatype: Capabilities — Base URL and other capability semantics.