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