Securing Bitbucket Server behind nginx using SSL
This page describes how to establish a network topology in which the nginx server acts as a reverse proxy for Bitbucket Server. Typically, such a configuration would be used when Bitbucket Server is installed in a protected zone 'behind the firewall', and nginx provides a gateway through which users outside the firewall can access Bitbucket Server.
The configuration described on this page results in a scenario where:
- External client connections with nginx are secured using SSL. Connections between nginx and Bitbucket Server are unsecured.
- Bitbucket Server and nginx run on the same machine.
- Bitbucket Server is available at https://mycompany.com:7990/bitbucket.
Also note that:
- We assume that you already have a running instance of nginx. If not, refer to the nginx documentation for instructions on downloading and installing nginx.
- SSL certificates must be installed on the server machine.
- Any existing links with other applications will need to be reconfigured using the new URL for Bitbucket Server.
- Securing Git operations between the user's computer and Bitbucket Server is a separate consideration - see Enabling SSH access to Git.
Be aware that Bitbucket Server does not need to run behind a web server, since it is capable of serving web requests directly; to secure Bitbucket Server when run in this way see Securing Bitbucket Server with Tomcat using SSL. Otherwise, if you want to install Bitbucket Server in an environment that incorporates nginx, this document is for you. (You can of course run Bitbucket Server behind nginx without securing client connections to nginx using SSL – we don't describe this option on this page.)
Note that the Atlassian Support Offering does not cover nginx integration. Assistance with nginx may be obtained through the Atlassian community from answers.atlassian.com or from an Atlassian Expert.
Step 1: Configure the Tomcat Connector
Find the normal (non-SSL) Connector directive in Tomcat's
<Bitbucket home directory>/shared/server.xml file, and add the scheme, proxyName, and proxyPort attributes as shown below. Instead of mycompany.com, set the proxyName attribute to your domain name that the nginx server will be configured to serve. This informs Bitbucket Server of the domain name and port of the requests that reach it via nginx, and is important for the correct operation of the Bitbucket Server functions that construct URLs.
<Connector port="7990"
protocol="HTTP/1.1"
connectionTimeout="20000"
useBodyEncodingForURI="true"
redirectPort="443"
compression="on"
compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript"
secure="true"
scheme="https"
proxyName="mycompany.com"
proxyPort="443" />For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.
Step 2: Set a context path for Bitbucket Server
By default, Bitbucket Server is configured to run with an empty context path; in other words, from the 'root' of the server's name space. In that default configuration, Bitbucket Server would be accessed at:
http://mycompany.com:7990/
For the example configuration on this page, we want Bitbucket Server to be accessed at:
https://mycompany.com:7990/bitbucket
In Tomcat's
<Bitbucket home directory>/shared/server.xml
file, set the context path to /bitbucket:
<Context path="/bitbucket" docBase="${catalina.home}/atlassian-bitbucket" reloadable="false" useHttpOnly="true">
....
</Context>If you use a context path, it is important that the same path is:
- appended to the context path of Bitbucket Server's base URL (Step 3).
- used when setting up the location for the p
roxy_passdirective (Step 4).
Step 3: Change Bitbucket Server's base URL
After re-starting Bitbucket Server, open a browser window and log into Bitbucket Server using an administrator account. Go to the Bitbucket Server administration area and click Server settings (under 'Settings'), and change Base URL to match the proxy URL (the URL that the nginx server will be serving).
For this example, use
http://mycompany.com:7990/bitbucket
(Note the context path included with this.)
Step 4: Configure nginx
Edit
/etc/nginx/nginx.conf
, using the example server configuration below, to configure nginx as a proxy server.
Put the proxy_pass directive in the location block, and specify the protocol, name and port of the proxied server in the parameter (in our case, it is http://localhost:7990):
server {
listen 443;
server_name mycompany.com;
ssl on;
ssl_certificate <path/to/your/certificate>;
ssl_certificate_key <path/to/your/certificate/key>;
ssl_session_timeout 5m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# Optional optimisation - please refer to http://nginx.org/en/docs/http/configuring_https_servers.html
# ssl_session_cache shared:SSL:10m;
location /bitbucket {
proxy_pass http://localhost:7990;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_redirect off;
}
}
Refer to http://nginx.org/en/docs/http/ngx_http_proxy_module.html.
Changes made in the configuration file will not be applied until the command to reload configuration is sent to nginx or it is restarted. To reload the configuration, execute:
nginx -s reloadThis command should be executed under the same user that started nginx.
Resources
You may find the following resources helpful in setting up Bitbucket Server behind nginx:
- http://nginx.org/en/docs/http/configuring_https_servers.html
- http://www.cyberciti.biz/tips/using-nginx-as-reverse-proxy.html
- https://mywushublog.com/2012/08/atlassian-tools-and-nginx/