Custom Tomcat Server – iceScrum

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

Java Application server

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 how to install iceScrum page.

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 v7 supports Java 8 (recommended) and Java 7. Java 6 is not supported anymore, and Java 9, 10 and higher are not supported.

Download:

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:

Connector

First, you need to configure the Tomcat server itself.

In the tomcatDir/conf/server.xml file, update the connector to use the NIO protocol and set the port to be used for iceScrum (here 8080). Be careful, the port must be free, and starting on port 80 requires admin privileges.

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

Java options

Then, you need to configure the Java options.

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.

Otherwise, add them to the CATALINA_OPTS environment variable (if you use Jetty, define the JAVA_OPTIONS variable instead).

-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

To write these options in the CATALINA_OPTS variable, you can create an script in tomcatDir/bin/ called setenv.sh (setenv.bat for Windows) and give it execution permissions on your OS.

export CATALINA_OPTS="$CATALINA_OPTS -Duser.timezone=UTC -Xmx1024m -XX:MaxPermSize=256m"
set "CATALINA_OPTS=%CATALINA_OPTS% -Duser.timezone=UTC -Xmx1024M -XX:MaxPermSize=256m"

Install the iceScrum WAR

First, you may want to remove everything in tomcatDir/webapps/ to start with a clean Tomcat installation.

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

By default, the iceScrum URL is http://localhost: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 by changing the name of the .war file, or removed if your rename it to ROOT.war.

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 open the how to install iceScrum documentation 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.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.

Custom URL / reverse proxy / https

It is common practice to use a reverse proxy (e.g. Apache or Nginx) 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) and even an https connection then a reverse proxy is not needed, everything can be defined on Tomcat.

If you use a reverse proxy, read the corresponding manual.


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