Upsource 2017.1 Help

In-cloud installationThings to configure after the first start

Proxy configuration

On this page:

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 supports WebSockets since version 1.3.13.
  • 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.3.13 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/
  • 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 enableproxy_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 theVirtualHost section:

RequestHeader set X-Forwarded-Proto "https"

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:

  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.

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.
Last modified: 13 July 2017