Upsource Web Help

Installing and configuring

The following document should help you install Upsource for the first time and configure it to an extent required to use it on a daily basis. If you want to upgrade your existing Upsource installation, follow the steps outlined under Upgrading your Upsource installation.


Simply download a new Upsource build from here and unzip the downloaded archive to a server directory of your preference. Later in this doc it will be referred to as the <upsource_home> directory.

Note: For system requirements and other important notes please read Things to check before starting up

What’s inside Upsource

The Upsource distribution bundles a set of different components including:

  • Upsource services including the frontend, VCS analysis, and monitoring

  • Apache Cassandra, the default bundled database

  • Hub, a JetBrains service for authentication, user and group management


Let’s agree on a few conventions to use for command line syntax below.

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

All commands listed below are Windows commands. If you’re working on a Linux or Mac OS X server, simply replace .bat with .sh.

Things to configure before starting Upsource

HTTP port

One thing you might want to change in Upsource settings before you start is the port that it would use for HTTP communications, especially if there’s already a service that uses port 8080 running on your server.

To make Upsource use a HTTP port other than the default port 8080, run the following command:

<upsource_home>\bin\upsource.bat configure --listen-port 1111

where 1111 is the port number you want to use.

HTTP proxy

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 for to access your Upsource installation):

<upsource_home>\bin\upsource.bat configure --listen-port 1111 --base-url

Now configure headers in your proxy server, and you’re done. Configuration guidelines for Nginx and Apache HTTP Server are provided below.

Nginx configuration

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

Here’s a sample Nginx header configuration:

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.local.domain:1111/;

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

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

ProxyRequests off
ProxyPass / ws://
ProxyPassReverse / ws://

ProxyPass /
ProxyPassReverse /

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"

IIS reverse proxy

To use IIS and ARR as a reverse proxy:

  1. Install ARR from here

  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 on the right pane

  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. Tick the Enable proxy checkbox and then click Apply. Leave the default values in place.

  11. In the Connections pane, under Sites, highlight Default Web Site
  12. Double-click the URL Rewrite feature, and click Add Rule(s)… in the Actions pane
  13. Add a reverse proxy rule, with server name: localhost:1111 (replace with real location and port of your Upsource service)
  14. Open created rule, check rewrite url, add server variables:

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

Resource limits on Linux

If you run Upsource on Linux, insufficient resource limits may result in a number of errors. To prevent that, we recommend to set:

  • maximum open files to 100000
  • memory locking and address space limit to unlimited.
  • number of processes to 32768

You can do it by adding the following lines to the /etc/security/limits.conf file:

* - memlock unlimited
* - nofile 100000
* - nproc 32768
* - as unlimited

Disable conflicting software

If you run Upsource on Windows, please disable all anti-viruses, Windows Defender, and Windows Search service for Upsource root directory, as they may conflict with Upsource processes.

You are now ready to launch Upsource

As soon as you have made all configuration changes that are relevant in your environment, you can proceed to start Upsource.