Reverse Proxy (Apache, Nginx) – iceScrum

Documentation This documentation applies only to iceScrum v7.
For old iceScrum R6, read the documentation or migrate.

Reverse proxy

It is common practice to use a reverse proxy in front of a Java Application Server, but it is optional: iceScrum works fine without a reverse proxy!

If you just want to use a custom domain name and port (e.g. http://icescrum.mydomain.com) then a reverse Proxy is not needed, you should be able to define everything either with Tomcat and icescrum.war, icescrum.jar or docker.

The reverse proxy support is not trivial because iceScrum uses the websocket technology that needs dedicated configuration. Also, you need to inform iceScrum about its external URL (port, protocol etc.) for it to perform properly. This documentation explains how to do so.

Context

By default, the iceScrum URL is http://yourhost:8080/icescrum. In such case, the context, which is the part of the URL just after the domain name and the port, is icescrum.

It can be changed or removed, but the context must be the same for the exposed external URL and the internal one.

That means that if you want an empty context on the external URL, e.g. www.icescrum.mydomain.com then you will have to set an empty context on the internal one too: e.g. http://127.0.0.1:8080. See the installation documentation to learn how to do that.

The following examples assume that iceScrum runs with an empty context on http://127.0.0.1:8080. If it runs on http://127.0.0.1:8080/icescrum or another port, replace the URL in the configuration accordingly.

Nginx

Here is an example mapping a server 80 port to an iceScrum installation available on http://127.0.0.1:8080:

http {
    # Required for websockets
    map $http_upgrade $connection_upgrade {
            default Upgrade;
            ''      close;
    }
    server {
        listen 80 default_server;
        charset utf-8;
        location /stream {
            proxy_pass         http://127.0.0.1:8080;
            proxy_http_version 1.1;
            proxy_set_header   Upgrade $http_upgrade;
            proxy_set_header   Connection $connection_upgrade;
            proxy_buffering    off;
        }
        location / {
            proxy_pass           http://127.0.0.1:8080;
            proxy_set_header     Host $http_host;
            proxy_set_header     X-Real-IP $remote_addr;
            proxy_set_header     X-Forwarded-For $proxy_add_x_forwarded_for;
            # Required to tell iceScrum its external port
            proxy_set_header     X-Forwarded-Port 80;
            # For large project export you may need to increase it further
            proxy_read_timeout   600s;       
            # Cap the max size for attachments           
            client_max_body_size 100m;                
        }
    }
}

Apache

You need the following Apache mods:

  • mod_proxy_http
  • mod_proxy_wstunnel: you may need to upgrade Apache to have this one
  • mod_headers
  • mod_rewrite

iceScrum is not compatible with mod_proxy_ajp.

Here is an example mapping a server 80 port to an iceScrum installation available on http://127.0.0.1:8080:

<VirtualHost *:80>
    ServerName myserver.com
    ProxyPreserveHost On
    # The order is important here
    ProxyPass         /stream/ ws://127.0.0.1:8080/stream/
    ProxyPassReverse  /stream/ ws://127.0.0.1:8080/stream/
    ProxyPass         /        http://127.0.0.1:8080/
    ProxyPassReverse  /        http://127.0.0.1:8080/
    # Required for websockets
    RewriteEngine on
    RewriteCond %{QUERY_STRING} ^((?!X-Atmosphere-Transport=websocket).)*$ [NC]
    RewriteRule ^/stream/app http://127.0.0.1:8080/stream/app$1 [P]
    # Required to tell iceScrum its external port
    RequestHeader set X-Forwarded-port "80" 
</VirtualHost>

HTTPS / SSL

First, you need to tell iceScrum that it will be used behind an https proxy:

  • Tomcat + icescrum.war
    Add the scheme and proxyPort attributes to your connector in server.xml:

    scheme="https"
    proxyPort="443"
    
  • icescrum.jar
    Add the httpsProxy=true option in the startup command.
  • Docker
    See the corresponding documentation.

For the actual SSL configuration, please refer to the documentation of your reverse proxy.

Then, define the appropriate headers:

  • Apache
        RequestHeader set X-Forwarded-Port "443"
        RequestHeader set X-Forwarded-Proto "https"
    
  • Nginx
        proxy_set_header X-Forwarded-Port 443;
        proxy_set_header X-Forwarded-Proto https;
    


Try it for free now
All you need for your Agile project management