Operating system

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

Java

iceScrum v7 requires Java 7 or 8. Java 6 is not supported anymore, and Java 9, 10 and higher are not supported.

You can download the latest Java 8 version for your platform here.

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

Database

A very important step is the choice of your database management system. iceScrum comes with an embedded H2 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 (5.x), PostgreSQL (9.x to 11.x), MS SQL Server or Oracle (Oracle is available only for paying licenses). If you do so, create and empty database for iceScrum, usually named icescrum, with a proper charset/collation, we strongly recommend UTF-8.

MYSQL had a weird behavior about UTF-8, here is how to create the empty database with the correct UTF8 charset on:

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

Be aware that it will change the default charset connection of your MySQL Server. Most of the apps that use MySQL will take care of their own encoding so it should not impact other apps.

CREATE DATABASE `icescrum` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

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.

Emails

Invitations, notifications when stories are updated and password retrieval all require iceScrum to send emails. Thus, to enable the features you need to provide iceScrum with 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 “Technical setting” field. Usually only of them is required but if you need to combine them, separate them by a comma.

• If you use anonymous 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,mail.smtp.ssl.protocols=TLSv1.2

• 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,mail.smtp.ssl.protocols=TLSv1.2

License

In order to benefit from all the iceScrum Apps in addition the core features, you can optionally enter a license. Licenses are either annual or perpetual, include support and enhance iceScrum with a lot of additional features provided as Apps. You will find the licensing options in our pricing page.

You can activate a free 14 days license to try all the Apps, they will just be disabled at the end of the trial period and iceScrum will keep working normally.

Read more in the license activation documentation.

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 (or close the command line) 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 license, you can update your settings in the administration panel, see the settings administration documentation,
• if you don’t have an license or if you need to update settings manually, follow the config.groovy documentation.

Support emojis from previous version (v7.7 or before)

If you already have an iceScrum server installed and you upgraded to v7.8 or later you may need to upgrade you database schema to see emojis. It will depends on your database. For PostgreSQL, SQL Server, H2 Database you will have nothing to do to use enjoy emojis :).

MySQL special case

For MySQL you need to change your database schema from utf8_general_ci to utf8mb4 charset. This is only needed for an existing iceScrum server with MySQL database created with a version before v7.8. If you have a fresh install while reading this guide you have nothing to do.

Before doing anything make a full backup of your database.

First you need to check that your MySQL server version is 5.5.3 or later. If not you must upgrade your MySQL server first.

Once you have a compatible MySQL server, you will need to make some changes in your my.cnf to add or change as follow:

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

Be aware that it will change the default charset connection of your MySQL Server. Most of the apps that use MySQL will take care of their own encoding so it should not impact other apps.

Then:

• 1 – Stop iceScrum
• 2 – Restart your MySQL server
• 3 – Start iceScrum
• 4 – Go to a textarea field and type “:” and verify that you have emojis suggestion list that shows up.
• 5 – Enjoy 😀

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 On-Premise paying licenses come with dedicated support (email, skype, phone).

Common questions / issues

Starting iceScrum at server startup
With icescrum.jar, starting iceScrum is a simple command. Thus, starting iceScrum automatically at your server startup is not specific to iceScrum at all, it is rather specific to your operating system. You should find plenty of resources on the internet that explain how to start a command automatically at your OS startup. There is just one thing that you should keep in mind: if iceScrum requires other services on the same server, e.g. a local MySQL or mail server, then they will need to be started at server startup as well.

Common errors

• 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.
• iceScrum seems to be slow (more than 10 seconds to load a simple page):
  • 1 – If you use a reverse proxy and your tomcat server is serving on localhost please try using 127.0.0.1 on your reverse proxy and restart proxy & tomcat.
  • 2 – Try to increase tomcat memory settings with an higher Xmx value.
  • 3 – Check your database if the settings are corrects.
• 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.
• java.io.FileNotFoundException:
  This error probably indicates that iceScrum cannot create files because it lacks permissions on the file system. Ensure that the user who starts iceScrum has the appropriate permissions on the directory where iceScrum is started from.
• Error when exporting (postits etc.) / java.awt.AWTError: Assistive Technology not found:
  Try executing something like:

  sed -i 's/^assistive_technologies=/#&/' /etc/java-8-openjdk/accessibility.properties

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 the command from.

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 a 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.