Teamscale Docs

Appearance

How to access Teamscale via a Reverse Proxy ​

Instead of making Teamscale directly accessible from the web you can consider operating Teamscale behind a reverse proxy, such as NGINX or Apache. Reverse proxies allow you to fulfill certain requirements, such as different authentication mechanisms or HTTPS support. Moreover, you can seamlessly redirect traffic to different Teamscale instances, e.g., if you want to upgrade to a new version of Teamscale.

General considerations ​

Before looking into the configuration that is specific to a reverse proxy solution, some general considerations should be taken into account.

Public Teamscale URL ​

The most important one is the URL that Teamscale will be accessible. In practice there are two options:

  • Teamscale is accessible via the domain root, e.g., http://teamscale.mydomain.tld
  • Teamscale is accessible via a subpath, e.g., http://mydomain.tld/teamscale

Both scenarios can be achieved with or without a reverse proxy. Especially if you want to provide another service (e.g. http://mydomain.tld/other-service) you may want to use a reverse proxy.

Using subpaths

It is highly recommended to configure the subpath of the reverse proxy and Teamscale exactly the same way to avoid redirect and path encoding issues.

In practice this means:

  • If Teamscale is accessible via the domain root, do neither specify a subpath in the reverse proxy nor in Teamscale
  • If Teamscale should be accessible via a subpath, configure the reverse proxy and Teamscale using exactly the same subpath. Configuring a different or no subpath in Teamscale is error-prone and requires advanced knowledge of the used reverse proxy.

The subpath of Teamscale can be configured in teamscale.properties using the following property (if the property is not set, no subpath is configured):

properties
server.urlprefix=teamscale

Restrict direct access to Teamscale ​

In the default configuration Teamscale is listening to port 8080 and is available from any browser that can access the server Teamscale is running on. You can restrict direct access to Teamscale in several ways, so access via the reverse proxy cannot be circumvented:

  • If Teamscale and the reverse proxy are running in Docker containers, please use common Docker networking techniques to prevent access, e.g. not exposing the Teamscale port to the host but only to a Docker-network.
  • If Teamscale and the reverse proxy are running on the same server without Docker, one can ensure that the instance is reachable only from the local machine by specifying the bind hostname in teamscale.properties:
    properties
    server.bind-hostname=localhost
  • If Teamscale and the reverse proxy are running on different servers, firewall rules may be used.

NGINX ​

NGINX is a HTTP and reverse proxy server that runs under Windows and Linux. It supports different authentication mechanisms or HTTPS termination and is a lightweight alternative to Apache HTTP Server or Microsoft IIS. You can find a complete nginx configuration in our example Docker setup, which follows security best practices and can handle multiple Teamscale instances.

Basic configuration ​

Incomplete Configuration Examples

The following configuration snippets only represent incomplete configuration examples to demonstrate certain use cases. Before deploying, make sure the nginx configuration follows the security guidelines of your organisation. The Mozilla SSL Configuration Generator might serve as a starting point for a secure configuration.

Serve from domain root ​

The following configuration may be used as a starting point if Teamscale should be served at the domain root. It should be adopted to the specific use case according to the documentation.

nginx
events {
  worker_connections 1024;
}

http {
  # Do not display the server version
  server_tokens off;

  server {
    # This is the default server listening on port 80
    listen 80 default_server;

    location / {
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $server_name;
      proxy_set_header X-Forwarded-Prefix "";
      proxy_set_header X-Forwarded-Port 80;
      
      set $teamscaleHost localhost;
      proxy_pass http://$teamscaleHost:8080;
    }
  }
}

The proxy_pass argument to the Teamscale server is extracted as variable $teamscaleHost. This prevents issues with DNS caching that may yield to 502 Bad Gateway errors. You can specify the hostname directly, e.g., proxy_pass http://localhost:8080 if Teamscale is running on the same network or can be accessed via localhost.

WARNING

Ensure that the argument of proxy_pass is specified as protocol://hostname:port and does not include a subpath, even not a trailing slash, e.g. protocol://hostname:port/. Specifying a subpath (URI) will yield to normalization of the request URL before it is passed to Teamscale.

Serve from subpath ​

If Teamscale should be served from a subpath, only the location in the nginx configuration needs to be changed. The following example shows the configuration for the subpath /teamscale:

nginx
    location /teamscale {
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $server_name;
      proxy_set_header X-Forwarded-Prefix "/teamscale";
      proxy_set_header X-Forwarded-Port 80;
      
      set $teamscaleHost localhost;
      proxy_pass http://$teamscaleHost:8080;
    }

WARNING

Do not add the subpath to proxy_pass. Instead the subpath needs to be defined in teamscale.properties and set to, e.g., server.urlprefix=teamscale.

The "X-Forwarded-*" headers need to reflect how Teamscale is exposed to the end user.

Advanced configuration ​

Redirecting the domain root ​

If you have multiple TS instances mounted on subdirectories (e.g. /teamscale, /staging etc.), you can redirect the root URL (the server name without any path) to one of these:

nginx
location = / {
    return 301 https://$host/teamscale;
}

Apache httpd ​

Apache is a open-source HTTP server that supports different authentication mechanisms and HTTPS termination. With the mod_proxy Module other applications can be reverse-proxied.

TIP

Apache HTTP Server is mostly used to manage larger domains and sites. Especially for the simple scenario of serving Teamscale on the domain root, the use of NGINX is recommended.

The following configuration may serve as a starting point if Teamscale should be served at a subpath.

txt
ProxyPass /teamscale
  http://localhost:8080/teamscale nocanon
ProxyPassReverse /teamscale
  http://localhost:8080/teamscale
ProxyRequests Off

# This is important, as otherwise some URLs are blocked by Apache
AllowEncodedSlashes NoDecode

Depending on your configuration and goals, slightly different and additional directives are required. Please refer to the Apache manual for more information.