Hub 2023.3 Help

Reverse Proxy Configuration

You can set up Hub to work behind a reverse proxy server.

The process that you use to enable this setup consists of the following steps:

  1. Configure Hub to point to the base URL of the proxy server.

  2. Configure the headers of your proxy server. This page includes guidelines for Apache, IIS, and NGINX servers.

Prerequisites

To get the best performance from services that are connected to your Hub installation, your proxy server should support HTTP/2. For most servers, the HTTP/2 protocol only works with HTTPS connections, which means that you need to secure your connections with a SSL/TLS certificate.

You also need to ensure that the OpenSSL library that is used by the reverse proxy server is version 1.0.2 or later. With earlier versions of OpenSSL, users connect using the legacy HTTP/1.1 specification, which lacks the performance benefits of an HTTP/2 connection.

The instructions on this page assume that these requirements are met. Use the following list to determine which server version is required to support this setup:

Server

Minimum Version

Apache

2.4.17

IIS

10.0 version 1709

NGINX

1.11.7

HTTP Strict Transport Security

We also strongly recommend that you set up your reverse proxy server to use HTTP Strict Transport Security (HSTS). This protects your installation against possible man-in-the-middle attacks, where the redirect from the HTTP to the HTTPS version of the site can be exploited to direct a user to a malicious site instead of the secure version of the original page.

The instructions for proxy server header configurations that are provided on this page include the directives that support HSTS.

Change the Base URL of your Hub Server

You can change the base URL for your Hub server from the command line using the configure command.

Always execute the configure command on behalf of the OS user that runs the Hub service. This command creates configuration files and folders. The Hub service user should have sufficient permissions to access these files and folders.

If you ever need to change the base URL for your running Hub instance, use the configure command with the --base-url argument.

To change the Base URL of the Hub service

  1. Stop Hub: docker exec <containerId> stop

  2. Execute the following command:

    docker run --rm -it \ -v <path to conf directory>:/opt/hub/conf \ jetbrains/hub:<version> \ configure --base-url=https://hub.mydomain.com:XXXX

    • https://hub.mydomain.com is the address of your proxy server.

    • XXXX is the port number that your proxy server listens to.

  3. Start Hub: docker start <containerId>

To execute these commands in an MSI installation, open the Command Prompt window as an administrator.

To change the base URL of your Hub server:

  1. Stop the Hub service. For specific instructions, see Stop and Restart the Hub Service.

  2. In a command-line interface, change the directory to <hub_home>\bin.

    For an MSI installation, the <hub_home> directory is the location where the MSI distribution was installed. The default installation directory is C:\Hub

  3. Enter the following command:

    hub.bat configure --listen-port 1111 --base-url https://hub.mydomain.com:XXXX

    • 1111 is the port number that your Hub server listens to.

    • https://hub.mydomain.com is the address of your proxy server.

    • XXXX is the port number your proxy server listens to.

  4. Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, or NGINX.

  5. Start the Hub service. For specific instructions, see Stop and Restart the Hub Service.

To change the base URL of your Hub server:

  1. Stop the Hub service. For specific instructions, see Stop and Restart the Hub Service.

  2. In a command-line interface, change the directory to <hub_home>/bin.

    For a ZIP installation, the <hub_home> directory is the location where the ZIP distribution was unpacked during installation.

  3. Enter the following command:

    hub.sh configure --listen-port 1111 --base-url https://hub.mydomain.com:XXXX

    • 1111 is the port number that your Hub server listens to.

    • https://hub.mydomain.com is the address of your proxy server.

    • XXXX is the port number your proxy server listens to.

  4. Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, or NGINX.

  5. Start the Hub service. For specific instructions, see Stop and Restart the Hub Service.

To learn more about the options for configuring the base URL and listen port for your Hub installation, see Change the Base URL or Listen Port.

Configure Proxy Server Headers

To configure the headers for your proxy server, follow the guidelines that are specific to your server. Configuration guidelines for Apache HTTP Server, IIS, and NGINX are provided below.

Apache HTTP Server Configuration

To use an Apache HTTP Server as a reverse proxy, you need to run an a2enmod script and add directives to a .conf file on your server.

Requires Apache httpd version 2.4.17 or later.

To set up an Apache HTTP Server as a reverse proxy:

  1. Use the following a2enmod script to enable the headers, rewrite, proxy_http, ssl, and http2 modules:

    $ a2enmod headers $ a2enmod rewrite $ a2enmod proxy_http $ a2enmod ssl $ a2enmod http2

  2. Add the following directives to the VirtualHost section of a relevant .conf file:

    Protocols h2 http/1.1 RequestHeader set X-Forwarded-Proto "https" DefaultType none RewriteEngine on AllowEncodedSlashes on RewriteCond %{QUERY_STRING} transport=polling RewriteRule /(.*)$ http://127.0.0.1:1111/$1 [P] ProxyRequests off ProxyPass / http://127.0.0.1:1111/ ProxyPassReverse / http://127.0.0.1:1111/ SSLEngine On SSLCertificateFile <path_to_certificate> SSLCertificateKeyFile <path_to_key>

  3. Set the following variables to match your Hub configuration:

    • Replace 1111 with the actual port number that your Hub server listens to.

    • Set the value for the <path_to_certificate> to the location of the SSL/TLS certificate for your server.

    • Set the value for the <path_to_key> to the location of the PEM-encoded private key file for the server certificate.

  4. Add the additional HSTS header to the HTTPS VirtualHost directive. Max-age is measured in seconds.

    # Guarantee HTTPS for 1 Year including subdomains Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"

    Note that this header is only valid on a HTTPS VirtualHost.

  5. Add a server-side redirect to upgrade non-HTTPS connections the first time the site is accessed. Add this to the non-HTTP VirtualHost.

    [...] ServerName myHubService.com Redirect permanent / https://myHubService.com/

    Replace myHubService.com with the actual domain name of your Hub server.

IIS Server Configuration

To use an IIS server as a reverse proxy, you need to use the Application Request Routing (ARR) extension.

Requires IIS version 10.0 version 1709 or later.

To set up an IIS server as a reverse proxy:

  1. Download and install the Application Request Routing (ARR) extension from the Microsoft website.

  2. In IIS Manager, connect to the IIS server - in this case, localhost.

  3. Highlight the server in the Connections pane.

  4. Double-click URL Rewrite.

  5. Click View server variables in the right pane.

  6. Add the following server variables to the list:

    HTTP_X_FORWARDED_HOST HTTP_X_FORWARDED_SCHEMA HTTP_X_FORWARDED_PROTO

  7. Highlight the server in the Connections pane.

  8. Double-click Application Request Routing Cache.

  9. Click Server Proxy Settings under the Proxy heading in the Actions pane.

  10. Select the Enable proxy checkbox.

  11. Deselect the Reverse rewrite host in response headers checkbox, then click Apply.

  12. In the Connections pane, under Sites, select Default Web Site.

  13. Double-click the URL Rewrite feature, then click Add Rule(s) in the Actions pane.

  14. Add a reverse proxy rule with the server name: localhost:1111 (replace with the real location and port of your Hub service).

  15. Open the rule, check the rewrite URL, and add the following server variables:

    • Set the HTTP_X_FORWARDED_HOST variable to {HTTP_HOST}.

    • Set the HTTP_X_FORWARDED_SCHEMA variable to https.

    • Set the HTTP_X_FORWARDED_PROTO to https.

  16. Make sure that anonymous authentication is enabled:

    • In the Sites section of the Connections pane, select Default Web Site.

    • Double-click Authentication, select Anonymous, then click Enable in the right pane.

  17. Add a new SSL binding to the Default Web Site.

    • The address that the SSL binding listens to (Host URL) should match the Hub base URL.

    • The certificate that you choose should correspond to the server DNS address.

  18. Configure the HTTP Strict Transport Security (HSTS) settings for the Default Web Site

    • Set the enabled attribute for the <hsts> to true.

    • Specify a value for the max-age attribute. For example, 31536000 (one year, in seconds).

    • Set the values for the includeSubDomains and redirectHttpToHttps to true as well.

    For specific instructions, please refer to the IIS configuration reference.

NGINX Server Configuration

The basic requirements for configuring an NGINX server as a reverse proxy consist of the following steps:

Requires NGINX version 1.11.7 or later.

To configure NGINX reverse proxy headers:

  1. Open the configuration file for your NGINX server. By default, the configuration file is named nginx.conf. The default directory is either /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx.

    You can find the exact location of the configuration file by entering nginx -V in a command line interface.

  2. Update the server directive and add the proxy_set_header and proxy_pass directives in your configuration file. Use the following sample as a guide:

    server { listen 443 ssl http2; ssl_certificate <path_to_certificate>; ssl_certificate_key <path_to_key>; server_name localhost; add_header Strict-Transport-Security max-age=31536000; location / { proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_pass http://hubmachine.domain.local:1111; } }

  3. Set the following variables to match your Hub configuration:

    • listen 443 is the port number that you specified in the --base-url parameter.

    • proxy_pass http://hubmachine.domain.local:1111 is the path to your Hub server with the port that you specified with the -–listen-port command.

  4. Save and close your configuration file.

  5. Check for errors in your NGINX configuration by stopping and starting the server with the following commands:

    sudo nginx -s stop sudo nginx

    Alternatively, you can reload the configuration with the following command:

    sudo nginx -s reload

If you use a Java keystore, you need to convert it to the PKCS #12 format to use a NGINX server as an SSL-terminating proxy. The following procedure shows you how to convert the keystore using keytool and openssl.

To convert a Java keystore to PKCS #12 format:

  1. Use keytool to convert your current .jks file to the PKCS #12 key store format .p12:

    keytool -importkeystore -srckeystore oldkeystore.jks -destkeystore newkeystore.p12 -deststoretype PKCS12 Enter destination keystore password: [enter private key password from oldkeystore.jks, it will be password for newkeystore.p12] Re-enter new password: [same as above] Enter source keystore password: [enter password for oldkeystore.jks] ... Enter key password for <key alias name> [enter private key password from oldkeystore.jks] ...

    You will be required to enter a "destination keystore password". If your .jks keystore contains a private key with a password, then the "destination keystore password" should equal the password of the private key.

  2. List the contents of the new keystore file:

    keytool -deststoretype PKCS12 -keystore newkeystore.p12 -list Enter keystore password: [enter password for newkeystore.p12 provided on step 1] ...

  3. Extract the .pem file (certificate) from the .p12 keystore:

    openssl pkcs12 -nokeys -in newkeystore.p12 -out certfile.pem Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...

  4. Extract the unencrypted key file from the .p12 keystore:

    openssl pkcs12 -nocerts -nodes -in newkeystore.p12 -out keyfile.key Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...

Troubleshooting

If you experience problems with Hub when you run the service behind a reverse proxy, see if the following condition applies.

Condition — Users are periodically logged out of Hub or other connected services

Cause

Solution

Hub uses a hidden inline frame to refresh authentication tokens. If you have set the value for the X-Frame-Options header to DENY for your reverse proxy server, users are logged out when their tokens expire.

All responses that contain static content from Hub set the value for the X-Frame-Options header to SAMEORIGIN. To preserve this value, configure your reverse proxy server to use the X-Frame-Options: SAMEORIGIN directive for all static content from Hub. For more information, see X-Frame-Options.

Last modified: 27 February 2024
TLS Server Certificates and KeystoresSwitch Between Third-party Proxy and Built-in TLS