iceScrum is a Java web application so it needs to run on a Java web application server. We provide a convenient package which already contains both iceScrum and a preconfigured Tomcat server in the form of a Java ARchive (JAR) file: icescrum.jar. It is the easiest way to install iceScrum, if you want to use it please refer to the install guide.
However, you can also get it as a Java Web Application ARchive (WAR): icescrum.war, in order to run it on your own application server.
It requires a container compatible with Servlet 3.0. We recommend the use of Tomcat, a widely used open source Servlet container. If needed, you can use another application server (e.g. Jetty) but this guide explains the install procedure for Tomcat only.
We will use the name tomcatDir to represent the directory where Tomcat is installed. The user who starts Tomcat must have write permissions on tomcatDir.
Java and Tomcat versions
iceScrum R6, now obsolete, requires Java 6 or 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:
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:
The following flags are usually already configured by default, but we recommend that you check that they are provided to the JVM:
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.
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.
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.
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.
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.
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/
Configure the Tomcat server so the server knows that it uses https by adding this attribute to the connector:
- 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.