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.

Java

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.

Database

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.

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"

Emails

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

mail.smtp.auth=false

• If your email server is accessible through SSL then enter this (this example works for smtp.gmail.com)

mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

• If your email server is accessible through TLS then enter this (this example works for smtp.live.com, i.e. Hotmail/Live/Outlook webmail):

mail.smtp.starttls.enable=true

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:

• if you have an iceScrum Pro license, you can update your settings in the administration panel, see the settings administration documentation,
• if you don’t have an iceScrum Pro license or if you need to update settings manually, follow the config.groovy documentation.

Support

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(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
• 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 prodDba.properties java.io.FileNotFoundException: prodDba.properties.new (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.

Logging

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.