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.
Downloading
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
Conventions
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 https://upsource.mydomain.com
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 /(.*)$ 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"
IIS reverse proxy
To use IIS and ARR as a reverse proxy:
-
Install ARR from here
-
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 and HTTP_X_FORWARDED_SCHEMA 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.
- 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_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.