Use Validate behind a reverse proxy

This topic explains how Validate behaves when deployed behind a reverse proxy, the base.url service property, and how to configure and verify your reverse proxy setup.

Overview

A reverse proxy sits in front of Validate and terminates client connections, forwarding requests to the Validate (Tomcat) backend.

When Validate is deployed behind a reverse proxy, all generated or displayed URLs—such as import paths, CI build links, hosted installer links, and Web/API references—must use the externally reachable URL that end users access.

The base.url service property, configured through kwservice, tells Validate what its public-facing URL is so that it can generate correct external links, while the reverse proxy handles routing those external requests to the internal host and port.

Validate has been tested with several reverse proxy solutions, including NGINX, Apache HTTP Server, Caddy, and HAProxy, and supports both non‑SSL and SSL configurations (with some known limitations).

Configure reverse proxy

Prerequisites

  • An installed and running Validate server

  • A reverse proxy (through services such as NGINX or Apache HTTP Server) that is already configured and reachable by end users

  • A DNS entry for your public hostname (for example, validate.example.com)

To configure your reverse proxy settings in Validate:

  1. Use kwservice or validate service to set the external base URL in Validate:

    kwservice set-service-property klocwork base.url https://validate.example.com

    Restrictions for base.url property:

    • Use the full <protocol>://<host>:<port> format. (Port is optional if using the default for the protocol)

    • Only http and https protocols allowed

    • If the value is not valid, the command fails with a validation error

  2. Verify reverse proxy by browsing to the public-facing URL, such as https://validate.example.com. Confirm you can sign into Validate.

  3. Verify that authentication, downloads, and Web API calls also succeed via the public host.

Remove the base URL property

To remove the base.url property and revert to Validate using its internal host/port:

kwservice remove-service-property klocwork base.url

Limitations

The following are known limitations that can arise when running Validate behind an SSL reverse proxy.

  • Limited interactions with:

    • a configured kwtoolstore

    • fetching server projects from IDEA plugin

    • installation of Eclipse plugin hosted through Validate server

    • importing projects from another server

  • These utilities are currently unsupported:

    • validate_backup

    • validate_restore

You may also encounter limitations when importing projects from other servers through an Apache reverse proxy.

Troubleshooting

This section lists common issues with reverse proxy configuration and how to resolve them.

Validate works without SSL internally but breaks over HTTPS externally.

Cause: Missing or incorrect X-Forwarded-Proto headers or proxy SSL configuration.

Fix: Ensure that the forwarding headers are set correctly, for example, on NGINX:

proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host  $host;

Browser shows mixed‑content or redirects from HTTPS to HTTP.

Cause: Missing or incorrect X-Forwarded-Proto headers or proxy SSL configuration.

Fix: Ensure the proxy sets X-Forwarded-Proto https and terminates TLS.

Users can access Validate internally but not through the proxy hostname/path.

Cause: DNS or firewall not pointing to the proxy; or proxy location/VirtualHost not matching the host.

Fix: Verify DNS, open ports to the proxy, and confirm hostnames match.

Installer download created with the internal Validate server URL

Cause: base.url is not set, or is set incorrectly.

Fix: Set the base.url to the external proxy URL with kwservice set-service-property klocwork base.url <url>

CI build links point to the wrong host.

Cause: Tools resolved internal URLs.

Fix: Ensure base.url is set on the server before loading the CI build.

Some Validate pages load as blank when accessed through NGINX.

Cause: Some reverse proxies defaults for data buffering can be too low.

Fix: Consider adjusting buffering settings or disabling them, for example, in NGINX:

Copy 
# Disable proxy buffering
proxy_buffering off;
proxy_request_buffering off;

Command line tools (e.g., kwadmin load) return 502 errors when run through the proxy.

Cause: Timeouts too low for large operations or buffering interfering with streamed responses.

Fix: Increase your reverse proxy timeout settings, for example, on NGINX:

Copy 
proxy_read_timeout 600s;
  proxy_connect_timeout 600s;
  proxy_send_timeout 600s;