Proxy configuration

Overview

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):

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

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

Nginx configuration

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

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

        server {
            listen 2222;
            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;
            }
        }
        

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/
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; } }

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:

        $ a2enmod headers
        $ a2enmod rewrite
        $ a2enmod proxy_wstunnel
        $ a2enmod proxy_http
        

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

        RewriteEngine on
        AllowEncodedSlashes on

        RewriteCond %{QUERY_STRING} transport=polling
        RewriteRule /(.*)$ http://127.0.0.1:1111/$1 [P]

        ProxyRequests off
        ProxyPass /~socket.io/ ws://127.0.0.1:1111/~socket.io/
        ProxyPassReverse /~socket.io/ ws://127.0.0.1:1111/~socket.io/

        ProxyPass / http://127.0.0.1:1111/
        ProxyPassReverse / http://127.0.0.1:1111/
        

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:

RequestHeader set X-Forwarded-Proto "https"

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

Protocols h2 http/1.1

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:

          AllowEncodedSlashes on
          RewriteEngine on
          RewriteCond %{QUERY_STRING} transport=polling
          RewriteRule /(.*)$ http://upsource_machine:1111/upsource/$1 [P]
          ProxyRequests off
          RequestHeader set X-Forwarded-Proto "https"

          <Location /upsource/>
          ProxyPass http://upsource_machine:1111/upsource/
          ProxyPassReverse http://upsource_machine:1111/upsource/
          </Location>

          <Location /upsource/~socket.io/>
          ProxyPass ws://upsource_machine:1111/upsource/~socket.io/
          ProxyPassReverse ws://upsource_machine:1111/upsource/~socket.io/
          </Location>
        

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

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

IIS reverse proxy

To use IIS and ARR as a reverse proxy:

Install ARR from the IIS site.
Make sure your IIS server supports WebSockets. This IIS instruction explains how to install a WebSockets support module.
In IIS Manager, connect to the IIS server — in this case, localhost.
Highlight the server in the Connections pane.
Double-click URL Rewrite
Click View server variables on the right pane.
Add
HTTP_X_FORWARDED_HOST HTTP_X_FORWARDED_SCHEME HTTP_X_FORWARDED_PROTO
to the list
Highlight the server in the Connections pane.
Double-click Application Request Routing Cache.
Click Server Proxy Settings under the Proxy heading in the Actions pane.
Tick the Enable proxy checkbox and then click Apply. Leave the default values in place.
Clear the Reverse rewrite host in response headers checkbox and then click Apply.
In the Connections pane, under Sites, highlight Default Web Site.
Double-click the URL Rewrite feature, and click Add Rule(s)… in the Actions pane.
Add a reverse proxy rule, with server name: localhost:1111 (replace with real location and port of your Upsource service).
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)
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.
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.
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

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:

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

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.

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:

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
Proxy should allow HTTP OPTIONS requests.
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.