Upsource
 
2020.1

Proxy configuration

Last modified: 02 April 2021

Overview

note

If your only reason for using a third-party proxy is to set up a secure HTTPS/TLS connection between your Upsource server and its clients, consider using the Upsource's built-in TLS instead. You can configure and enable it in Configuration Wizard during the installation or upgrade procedures. You can also configure and switch the modes from HTTP to HTTPS and back in your current Upsource installation using the command line.

You can set up Upsource to work behind a reverse proxy server. There are two requirements that your environment should meet to make this possible:

  • Your proxy server must support WebSockets. For example, Nginx fully supports WebSockets starting with version 1.11.7.

  • Upsource should be hosted under root URL (/) on your virtual host.

If these requirements are met, start with configuring Upsource to use a base URL (the URL that end users will request to access your running Upsource installation):

where:

  • 1111 is the port number Upsource will listen to

  • http://upsource.mydomain.com is the address of your proxy server

  • and 2222 is the port number your proxy will listen to

note

<upsource_home>\directory_name should be read as "open the console and change directory to directory_name under Upsource home directory."

All commands listed here are Windows commands. If you're working on a Linux or macOS, simply replace .bat with .sh.

Nginx configuration

To ensure support for WebSockets, please use Nginx 1.11.7 or later.

Here's a sample Nginx header configuration (non SSL):

where:

  • listen 2222 is the port that you have previously specified as a --base-url parameter

  • proxy_pass http://upsourcemachine.domain.local:1111/ is the path to your Upsource machine with the port that you have previously specified using the -–listen-port command

Nginx SSL configuration goes as follows:

  • Configure base URL: 

    <upsource_home>\bin\upsource.bat configure --listen-port 1111 --base-url https://upsource.mydomain.com/

    note

    If you are going to configure your Upsource installation to use a built-in Hub, make sure that Upsource base URL hostname is resolvable from the Upsource server, as Upsource will use that hostname to communicate with its built-in HUB service.

  • Nginx configuration file: 

    server {
    listen 443 ssl;

    ssl_certificate <path_to_certificate>;
    ssl_certificate_key <path_to_key>;

    server_name localhost;

    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;

        # to proxy WebSockets in nginx
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://upsourcemachine.domain.local:1111/;
        proxy_pass_header Sec-Websocket-Extensions;
    }
}

note

To speed up Upsource's initial loading, you can instruct Nginx to use the http2 protocol. Just add http2 to the second line of the Nginx config file: listen 443 ssl http2;.

The http2 protocol will work for https connections only. The Nginx version should be 1.11.7 or newer.

Please refer to the corresponding Nginx documentation pages for a description of server_name, proxy_set_header, proxy_pass.

Apache HTTP server configuration

To ensure support for WebSockets, please use Apache HTTP Server 2.4.10 or later.

Make sure to enable proxy_wstunnel, proxy_http, rewrite modules (and optionally headers if you want to use SSL) using the a2enmod script:

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

where 1111 is the port number you configured Upsource to listen to.

If you want to use SSL, additionally add the following directives to the VirtualHost section:

To speed up Upsource's initial loading, you can instruct Apache to use the http2 protocol — add the following directive to the VirtualHost section:

Also make sure the module mod_http2 is installed and enabled. The http2 protocol will work for https connections only. The Apache HTTP version should be 2.4.17 or newer.

To configure Upsource in a non-root context (i.e. http://somesite.com/upsource/ ), use the following example:

where http://somesite.com/upsource/ is the Base URL

and http://upsource_machine:1111/upsource is the path to your Upsource machine.

note

If you are going to configure your Upsource installation to use a built-in Hub, make sure that Upsource base URL hostname is resolvable from the Upsource server, as Upsource will use that hostname to communicate with its built-in HUB service.

IIS reverse proxy

To use IIS and ARR as a reverse proxy:

  1. Install ARR from the IIS site.

  2. Make sure your IIS server supports WebSockets. This IIS instruction explains how to install a WebSockets support module.

  3. In IIS Manager, connect to the IIS server — in this case, localhost.

  4. Highlight the server in the Connections pane.

  5. Double-click URL Rewrite

  6. Click View server variables on the right pane.

  7. Add 

    HTTP_X_FORWARDED_HOST
HTTP_X_FORWARDED_SCHEME
HTTP_X_FORWARDED_PROTO
    to the list

  8. Highlight the server in the Connections pane.

  9. Double-click Application Request Routing Cache.

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

  11. Tick the Enable proxy checkbox and then click Apply. Leave the default values in place.

  12. Clear the Reverse rewrite host in response headers checkbox and then click Apply.

  13. In the Connections pane, under Sites, highlight Default Web Site.

  14. Double-click the URL Rewrite feature, and click Add Rule(s)… in the Actions pane.

  15. Add a reverse proxy rule, with server name: localhost:1111 (replace with real location and port of your Upsource service).

  16. Open created rule, check rewrite url, add server variables:

    • set HTTP_X_FORWARDED_HOST to {HTTP_HOST}

    • set HTTP_X_FORWARDED_SCHEME to https (if the IIS site is configured to https, else set to http)

    • set HTTP_X_FORWARDED_PROTO to https (if the IIS site is configured to https, else set to http)

  17. Make sure that Anonymous Authentication is enabled:

    • In the Connections pane, under Sites, highlight Default Web Site.

    • Double click Authentication, Select Anonymous, Click Enable in the right pane.

  18. Optional (not required for HTTP only access): if HTTPS access is desired, add a new SSL binding to the Default Web Site.

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

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

  19. Websocket compression is not supported by IIS and should be disabled upon Upsource start-up. When you are ready to start Upsource, start it with the following command to disable websocket compression:

    upsource.bat start --J-Dbundle.websocket.compression.enabled=false

note

If you are going to configure your Upsource installation to use a built-in Hub, make sure that Upsource base URL hostname is resolvable from the Upsource server, as Upsource will use that hostname to communicate with its built-in HUB service.

AWS Elastic Load Balancer reverse proxy

To ensure support for WebSockets, please use Application Load Balancer type.

To use Application Load Balancer as a reverse proxy:

  • Launch Application Load Balancer creation wizard and follow its steps:

    1. Configure Load Balancer: Add HTTPS listener either with the default SSL port 443 or any other port of your choice.

    2. Configure Security Settings: Either request a certificate from AWS or upload an existing one.

    3. Configure Security Groups: Select an existing security group which is associated with the machine where Upsource is deployed.

    4. Configure Routing: Proceed with the new group creation with HTTP protocol and the port that is defined via --listen-port property (port 1111 in our example - see below).

    5. Register Targets: Add Upsource instance to the list of Registered Targets.

After Application Load Balancer is created, configure Upsource base URL:

where:

  • 1111 is the port number Upsource will listen to and which was specified in Step 4 Configure Routing

  • upsource.mydomain.com is the DNS name of the load balancer, which can be found on the Load Balancer Description tab.

note

If you are going to configure your Upsource installation to use a built-in Hub, make sure that Upsource base URL hostname is resolvable from the Upsource server, as Upsource will use that hostname to communicate with its built-in HUB service.

Custom proxy rules limitations

If set up with an external Hub instance, Upsource may require CORS to make certain calls to Hub. The aforementioned configurations work fine and don't require any further tuning. Additional custom proxy rules, however, may interfere with CORS, making login to Upsource impossible.

The following should be taken into account when external Hub is going to work behind a reverse proxy:

  1. Proxy rules should not block CORS-related HTTP headers:

    • Access-Control-Request-Method

    • Access-Control-Request-Headers

    • Access-Control-Allow-Origin

    • Access-Control-Allow-Credentials

    • Access-Control-Expose-Headers

    • Access-Control-Max-Age

    • Access-Control-Allow-Methods

    • Access-Control-Allow-Headers

  2. Proxy should allow HTTP OPTIONS requests.

  3. HTTP OPTIONS requests should not be a subject of proxy-enforced authentication, if any. For example, one may want to set up certificate-based authentication to comply with enterprise security policy. In that case authentication check should be skipped if incoming request is of OPTIONS type. OPTIONS requests cannot return any customer related data by itself, so it's safe to let them in.