Bitbucket Server context-path configuration when reverse proxy strips path prefix

Answer

When the reverse proxy removes the external prefix (e.g., maps /bitbucket/* to /*), set server.context-path to the internal path seen by the application – typically an empty value (or /) meaning the root of the Tomcat container.

Explanation

Bitbucket builds its URLs (clone links, REST endpoints, static resources) from server.context-path and the configured Base URL. If the proxy strips the prefix, the application receives requests at / internally. Setting server.context-path to the external prefix would cause double‑prefixing (e.g., /bitbucket/bitbucket/...) and break clone/fetch operations.

Confirmed facts

• Bitbucket does not automatically read X-Forwarded-Prefix; however, starting with Spring Boot 2.3 (Bitbucket 7.x) you can enable forwarded‑header handling by adding server.use-forward-headers=true to bitbucket.properties (or via JVM args).
• The Base URL in the Bitbucket UI must reflect the external URL that clients use (including any context‑path the proxy presents).
• Health‑check endpoints should target the internal path: when server.context-path is empty, use /status; if you retain a non‑root context, use <context-path>/status.
• SSH clone URLs never contain a context‑path and remain unchanged.

Steps for this case

1. Edit <BITBUCKET_HOME>/shared/bitbucket.properties (or <BITBUCKET_INSTALL>/bin/setenv.sh for JVM args) and set:

   # Internal path – empty because proxy strips the prefix
   server.context-path=
   # Enable forwarding of X‑Forwarded‑* headers (requires Bitbucket 7.x+)
   server.use-forward-headers=true
   

2. Restart Bitbucket (all nodes in a Data Center cluster) to apply the change.
3. In the Bitbucket UI → Settings → Server settings, set the Base URL to the external URL clients use, e.g., https://proxy-host/bitbucket (include the context‑path that the proxy presents).
4. Ensure the proxy forwards the required headers: X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-Port, and X-Forwarded-Prefix (the latter is the original /bitbucket prefix). Example NGINX snippet:

   proxy_set_header X-Forwarded-Host $host;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_set_header X-Forwarded-Port $server_port;
   proxy_set_header X-Forwarded-Prefix /bitbucket;
   

5. Configure the load‑balancer health check to hit the internal status endpoint:
   • If server.context-path is empty: GET https://internal-node-host/status.
   • If you kept a non‑root context: GET https://internal-node-host/<context-path>/status.
6. Verify:
   • Open https://proxy-host/bitbucket; the UI loads without redirect loops.
   • Clone URL shown in the UI is https://proxy-host/bitbucket/scm/... and a git clone succeeds.
   • REST call to https://proxy-host/bitbucket/rest/api/1.0/... returns expected JSON.
   • Health check returns {"state":"RUNNING"} with HTTP 200.
   • SSH clone URL ssh://git@proxy-host:7999/project/repo.git works unchanged.

Missing diagnostic detail

Please confirm your Bitbucket version (7.x or later) to verify that the server.use-forward-headers=true workaround applies. If you are running an older version (6.x or earlier), the forwarded‑header support is not available and you would need to retain the context‑path internally (i.e., set server.context-path=/bitbucket) and adjust the proxy to not strip the prefix.