Proxying and securing Bitbucket Server
This page provides an overview of some common network topology options for running Bitbucket Server, including running Bitbucket Server behind a reverse proxy and securing access to Bitbucket Server by using HTTPS (HTTP over SSL).
Note that Bitbucket Server does not need to run behind a web server – it is capable of serving web requests directly using the bundled Tomcat application server. On this page, 'connecting to Bitbucket Server' really means connecting to Tomcat, which is used to serve Bitbucket Server content.
On this page
Connecting to Bitbucket Server directly over HTTP
Connecting directly to Bitbucket Server (that is, Tomcat) is the default install configuration, as described in the Bitbucket Server install documentation.
When set up this way, the user accesses Bitbucket Server directly over HTTP, without using SSL – all communication between the user's browser and Bitbucket Server will be unsecured.
You may also wish to consider the following:
- Bitbucket Server, by default, will listen for requests on port 7990 – this port can be changed if required.
- The address with which to access Bitbucket Server, by default, will be http://<computer name>:7990. Change the base URL for Bitbucket Server if required.
- You can set the context path for Bitbucket Server if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Server.
- Securing Git operations between the user's computer and Bitbucket Server is a separate consideration - see Enabling SSH access to Git.
Securing access to Bitbucket Server using HTTPS
Access to Bitbucket Server can be secured by enabling HTTPS (HTTP over SSL) for the Tomcat application server that is bundled with Bitbucket Server. You should consider doing this, and making secure access mandatory, if Bitbucket Server will be internet-facing and usernames, passwords and other proprietary data may be at risk.
When set up in this way, access to Bitbucket Server is direct, and all communication between the user's browser and Bitbucket Server will be secured using SSL.
See Securing Bitbucket Server with Tomcat using SSL for configuration details.
Using a reverse proxy for Bitbucket Server
You can run Bitbucket Server behind a reverse proxy, such as Apache HTTP Server. You may wish to do this if you want to:
- use a different port number to access Bitbucket Server, particularly if you are Integrating JIRA Cloud with Bitbucket Server.
- use a different context path to access Bitbucket Server
When set up this way, external access to Bitbucket Server is via a reverse proxy, without using SSL. All communication between the user's browser and Apache, and so Bitbucket Server, will be unsecured, but users do not have direct access to Bitbucket Server. An example scenario is where Apache provides a gateway through which users outside the firewall can access Bitbucket Server.
See Integrating Bitbucket Server with Apache HTTP Server for configuration details.
Note that:
- Bitbucket Server, by default, will listen for requests on port 7990 – this port can be changed if required.
- Bitbucket Server (Tomcat) needs to know the URL (proxy name) that Apache serves.
- The address with which to access Bitbucket Server will be http://<proxy name>:7990. Change the base URL for Bitbucket Server if required.
- Any existing links with other applications will need to be reconfigured using this new URL for Bitbucket Server.
- You can set the context path for Bitbucket Server if you are running another Atlassian application, or Java web application, at the same hostname and context path as Bitbucket Server.
- Securing Git operations between the user's computer and Bitbucket Server is a separate consideration - see Enabling SSH access to Git.
Securing a reverse proxy using HTTPS
You can run Bitbucket Server behind a reverse proxy, such as Apache HTTP Server or nginx, that is secured using HTTPS (HTTP over SSL). You should consider doing this, and making secure access mandatory, if usernames, passwords and other proprietary data may be at risk. An example scenario is where Apache HTTP Server provides a gateway through which users outside the firewall can access Bitbucket Server.
When set up in this way, external access to Bitbucket Server is via a reverse proxy, where external communication with the proxy uses HTTPS. All communication between the user's browser and the reverse proxy will be secured, whereas communication between the proxy and Bitbucket Server will not be secured (it doesn't use SSL).
See the following pages for configuration details:
- Securing Bitbucket Server with Apache using SSL
- Securing Bitbucket Server behind nginx using SSL
- Securing Bitbucket Server behind HAProxy using SSL
Note that:
- The reverse proxy (for example, Apache) will listen for requests on port 443.
- Bitbucket Server, by default, will listen for requests on port 7990. Bitbucket Server (Tomcat) needs to know the URL (proxy name) that the proxy serves.
- The address with which to access Bitbucket Server will be https://<proxyName>:<proxyPort>/<context path>, for example https://mycompany.com:443/bitbucket
- Any existing links with other applications will need to be reconfigured using this new URL for Bitbucket Server.
- Bitbucket Server (Tomcat) should be configured to refuse requests on port 7990 and to redirect those to the proxy on port 443.
- Securing Git operations between the user's computer and Bitbucket Server is a separate consideration - see Enabling SSH access to Git.
- It would be possible to set up an SSL connection between the proxy server and Tomcat (Bitbucket Server), but that configuration is very unusual, and not recommended in most circumstances.
- Incidentally, note that Bitbucket Server 4.0 and later versions do not support
mod_auth_basic.