Java and Tomcat versions

iceScrum R6, now obsolete, requires Java 6 or 7.

Download:

• Java 7

If you already have another version of Java installed, it is not a problem: different versions can cohabit.

Here are the supported Tomcat versions, and the manual operations required to use them:

• Tomcat 7 (7.0.23 or greater), mandatory for R6: you need to remove the tomcatDir/lib/tomcat-jdbc.jar library.

Configuration

First, you need to configure the Tomcat server itself. In the tomcatDir/conf/server.xml file, configure the connector to use the NIO protocol and set the port to be used for iceScrum (start with the port 8080 if it is available, you will be able to change it later):

<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol" 
           connectionTimeout="2000" maxThreads="500" URIEncoding="UTF-8"/>

Then, you need to configure the CATALINA_OPTS environment variable (if you use Jetty, define the JAVA_OPTIONS variable instead).

A good place to define it is a tomcatDir/bin/setenv.sh script (setenv.bat for Windows), please read the Tomcat documentation for more information. If you use the Tomcat service manager on Windows then the options must be entered in the GUI rather than in a script and the memory options are entered in separate dedicated fields.

Add the following settings to the CATALINA_OPTS variable:

-Dicescrum.log.dir=/path/to/dir/where/i/can/write/

-Duser.timezone=UTC

-Dicescrum_config_location=/path/to/dir/where/i/can/write/config.groovy

-Xmx1024m

-XX:MaxPermSize=256m

The following flags are usually already configured by default, but we recommend that you check that they are provided to the JVM:

-Djava.awt.headless=true

-server

Don’t forget to remove the tomcatDir/lib/tomcat-jdbc.jar library. You may also want to remove everything in tomcatDir/webapps/ to start with a clean Tomcat installation.

Install the iceScrum WAR

Download icescrum.war here: https://www.icescrum.com/download/ (click on the “box icon”) and move it to the tomcatDir/webapps/ directory.

Start iceScrum

Once it is configured, you can start the Tomcat server by running the tomcatDir/bin/startup.sh script (startup.bat for Windows). Depending on how you installed it, tomcat can also be started as a service as so: service tomcat8 start. Tomcat will start iceScrum automatically if the WAR is found in the tomcatDir/webapps/ directory.

You can then go back to the install guide and follow the “Configure iceScrum” section in order to get started.

Troubleshooting

Here are some common issues related to custom application server:

• java.io.FileNotFoundException: /usr/share/java/jsp-api-2.3.jar Recent Debian Tomcat packages don’t include all Tomcat libraries for some reason, install them manually:
  sudo apt-get install libservlet3.1-java
• java.lang.NullPointerException at java.util.TimeZone.getAvailableIDs(TimeZone.java:594)
  This happens when creating a project when using latest Ubuntu Java 7 packages, because they don’t include Timezone support. Read the following for a workaround: http://blog.swwomm.com/2016/05/ubuntu-1604-with-java-7-timezone-data.html
• Related to exports (PDF etc.):
  Ensure that your JVM is configured in headless mode as explained in this guide and that you don’t use a not supported application server such as Tomcat8 or an unsupported JDK.
• Related to server URL (attachments, redirection after logging in, etc.):
  If you defined a custom URL (domain, port), please ensure that you defined the Server URL setting and the proper tomcat connector.
• java.lang.NoClassDefFoundError: javax/servlet/http/Part:
  Your application server doesn’t provide native support to Servlet 3.0. Tomcat 6 users, please refer to the software requirements section.
• java.lang.ClassNotFoundException: org.hsqldb.jdbcDriver (or com.mysql.jdbc.Driver)
  If you use Tomcat 7, you should remove the tomcat-jdbc.jar library from the tomcatDir/lib folder.
• java.lang.NullPointerException on CoyoteAdapter:
  Your Tomcat 7 version is probably outdated.
• Error messages in the Tomcat process when shutting down iceScrum:
  It’s a known problem that shouldn’t affect your application. We recommend that you check that the Java process has been really killed.

If it doesn’t help, please refer to the main troubleshooting documentation.

Reverse Proxy

It is common practice to use a reverse proxy in front of a Java Application Server. iceScrum works fine with Apache and nginx, however a proper configuration may require advanced knowledge and you may want to ensure that you need such a tool.

If you just want to use a custom domain name and port (e.g. https://icescrum.mydomain.com) then a reverse Proxy is not needed, you should be able to define everything at the Tomcat level.

• Apache:
  If you use an Apache server as a reverse proxy for your Tomcat server, you will need to use mod_proxy_http. iceScrum is not compatible with mod_proxy_ajp as it doesn’t support HTTP streaming / push. Here is an example VirtualHost configuration for iceScrum:

  ProxyRequests Off
  ProxyPreserveHost On
  ProxyStatus On
  ProxyPass		/icescrum/         http://localhost:8080/icescrum/
  ProxyPassReverse	/icescrum/         http://localhost:8080/icescrum/  
  

Due to a library we use, the context name (here /icescrum) 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, e.g. by renaming the .war from icescrum.war to ROOT.war, so iceScrum will be available internally on http://localhost:8080.

SSL

The first thing to do is to ensure that the server URL defined for iceScrum starts with https.

Then, there are several ways to configure the SSL connection, depending on whether you use a reverse Proxy, and which one you use:

• Tomcat alone: define a SSL connector as indicated in the Tomcat documentation
• Apache + Tomcat:

  Configure the Apache SSL connection as explained in the Apache documentation.

  Then, add a rule to the Apache VirtualHost so it rewrites 302 responses from your iceScrum servers. This ensures that end users receive an HTTPS location to redirect to:

  Header edit Location ^http://www.icescrum.example.com/ https://www.icescrum.example.com/

  OR

  Configure the Tomcat server so the server knows that it uses https by adding this attribute to the connector:

  scheme="https"

• nginx + Tomcat: it should work fine out of the box if you follow the nginx documentation. Don’t forget to set the X-Forwarded-Host header.