Install guide (R6) – iceScrum

Obsolete iceScrum documention (R6#14+) This documentation applies only to old iceScrum R6. For new iceScrum v7, click here.

This guide will help you through the installation procedure, which should be rather simple to follow. However, configuring a custom server environment may require time and advanced computing skills. That is why we provide install services, including custom configuration and remote installation. If you are interested, please contact us.

Hardware requirements

Here is an estimated minimal server configuration:

  • Processor: a modern one, e.g. 2GHz+, 2+ cores
  • RAM: 2GB+ (iceScrum requires at least 768MB but you also need RAM for the OS, applications etc.)
  • Hard drive: 10GB+ (iceScrum itself doesn’t require much space but you need space for the OS, DB, application server, user attachments etc.)

Please note that hardware requirements highly depend on your use of the tool (total number of users, number of concurrent users, other applications running on your machine…).

Software requirements

Operating system

We recommend the use of Ubuntu 12.04 LTS (Long Term Support). However, iceScrum can be used with other Linux distributions, Windows and Mac OS.


iceScrum R6 requires Java 6 or 7. Java 8 support is not available yet, it will be available in iceScrum v7.

You can download the latest Java 7 version for your platform here. If you already have another version of Java installed, it is not a problem: different versions can cohabit.

Be sure that the Java executable, java, is accessible (e.g. on Windows you can add its path to your PATH environment variable if necessary) by typing this in the Command Line:

java -version

Application server & Custom URL

iceScrum is a Java web application so it needs to run on a Java web application server. However, we provide a convenient package which already contains both iceScrum and a preconfigured Tomcat server under the form of a Java ARchive (JAR) file: icescrum.jar.

If you want to define a custom external URL different than the local URL, this is not possible with icescrum.jar but you can install iceScrum as a Java Web Application ARchive (WAR) file and on a custom application server for a custom URL configuration.

Start iceScrum

First, download the icescrum.jar file here:

Then, open a command line interface (e.g. Terminal on Mac or cmd on Windows) and open your download folder (using cd on Mac or dir on Windows). Provided that the java exectuable is accessible in your command line, type the following command to start iceScrum:

java -Xmx512M -XX:MaxPermSize=256m -jar icescrum.jar

Start iceScrum

The command may take a few minutes to start iceScrum. Then, open the URL provided in the command line in your favorite browser. It should display the iceScrum setup wizard that will help you configure your iceScrum server.

You can optionally customize the iceScrum URL by providing additional arguments to the command :

  • host=value: Defaults to the first external ip found or fallback to localhost. Should be set in order to use iceScrum correctly.
  • port=value: Defaults to 8080. If you want to set it to 80 you must start the command as an administrator.
  • httpsPort=value: Defaults to nothing. If you want to set it to 443 you must start the command as an administrator.
  • context=value: Defaults to icescrum, so iceScrum will be accessible at http://host:port/icescrum. If you want to access to iceScrum like this: http://host:port/ set the context like this: context=/

This URL must be the same internally and externally. If you want a custom URL then you rather need to install a custom application server.

Here is an example with custom options to open iceScrum on http://myhost:8081/app:

java -Xmx512M -XX:MaxPermSize=256m -jar icescrum.jar host=myhost
port=8081 context=app

Configure iceScrum

When you start iceScrum for the first time, a setup wizard will help you configure your server (available in iceScrum R6#14.2 and above). As a result, you will get an administrator account and the settings will be written in a file.

Server setup - Create the administration account


A very important step is the choice of your database management system. iceScrum comes with an embedded HSQLDB database so you can try iceScrum without needing to install or configure a DBMS. However, it is NOT suitable for production environments in terms of reliability and performances.

Thus, we recommend the use of one of the external DBMS compatible with iceScrum: MySQL, PostgreSQL, MS SQL Server or Oracle. If you do so, create and empty database for iceScrum, usually named icescrum, with a sensible charset/collation: we strongly recommend UTF-8.

With PostgresQL, be careful, you have to use the “public” schema otherwise iceScrum won’t restart.

Then, provide the JDBC connection URL (which is pre-filled according to the DBMS you chose) that includes your database name and iceScrum will take care of creating the database structure.

Server setup

If the setup refuses to go to the next step then please check that the settings entered in the current step are correct.

With Oracle, after the end of the setup and before the subsequent restart, add this to your config.groovy file:

dataSource.dialect = "org.hibernate.dialect.Oracle10gDialect"


Several important iceScrum features rely on the ability to send email. Such features are invitations, notifications when stories are updated and password retrieval. For that, iceScrum requires an external SMTP server.

You will need to enter the email server host, port and your username/password if your server requires authentication.

Then, you may have to add a technical setting in the “Setting” field:

  • If you use anyonymous authentication (no username/password) then enter this
  • If your email server is accessible through SSL then enter this (this example works for
  • If your email server is accessible through TLS then enter this (this example works for, i.e. Hotmail/Live/Outlook webmail):

Email server configuration (gmail)

Finish the setup

Once iceScrum is configured, depending on the settings you have changed, you may have to restart it. To do so, just kill the command and start it again. Then, you can start using it and follow the getting started guide.

The settings you have chosen can be updated later:


Any trouble using iceScrum? You should find some help here.


You may want to get help for your install and configuration. iceScrum developers can help you! We can install and configure your iceScrum server (contact us) and iceScrum Pro Standalone comes with dedicated support (email, skype, phone).

Common issues

Here are some common issues and how to solve them:

  • Related to configuration (DB, emails, etc.):
    First, try changing a trivial setting (like disabling registration) and see if it works. If so then it proves that your configuration is taken into account and that your specific setting may be wrong. Then, try trivial values for your settings (e.g. Gmail for emails) to see if the problem comes from your values.
  • Related to special character input (when creating items or importing a project):
    Ensure that your server DB has a sensible charset/collation as suggested in this guide. We recommend the use of UTF-8.
  • Related to network (DB, LDAP, emails, push):
    Check if you use a proxy or a firewall, it may block the connection. If you try to connect to an external server then try to reach it by another way (command line tool, etc.) to check if you have access to it.

Here are some common errors in icescrum logs and their meaning:

  • java.lang.NullPointerException at java.util.TimeZone.getAvailableIDs(
    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:
  • Infos: validateJarFile(/var/lib/tomcat7/webapps/icescrum/WEB-INF/lib/geronimo-servlet_3.0_spec-1.0.jar) – jar not loaded
    This message can be ignored. Geronimo-servlet is here to provide compatibility with Tomcat 6.
  • “Unknown column ‘text_as'” or “Unknown column ‘added'” on startup, marked as ERROR:
    These errors can be ignored. They are not actual errors: the column are missing because we removed them when migrating the database structure. The queries remain in order to allow migration from former versions.
  • java.sql.SQLException: File input/output error (Permission denied):
    This error indicates that iceScrum cannot create the default database files because it lacks permissions on the file system. Ensure that the use who starts iceScrum has the appropriate permissions on the directory where iceScrum is started from.

If this did not help you find the cause of your problem, please read the following sections about logs.


You should find a logs directory in the directory where you started Tomcat from or in the custom directory you have defined.

You may want to enable more log information. If you are using iceScrum Pro, you have to enable verbose logging in the settings administration. Otherwise, enable the debug setting in your config.groovy file:

icescrum.debug.enable = true

Then, have a look at the icescrum.log file. If you have an iceScrum Pro license then please contact us, we will be happy to help! Otherwise, post your issue with the logs on our community forums in order to get help.

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