Install and configure – iceScrum

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


Install iceScrum on your own server.

Get started

If you just want to try iceScrum, installing it may not be the best choice as we provide free hosting for public projects. To start using it, just create an account on our website and click on “My projects”. We also provide paying plans for private projects and even private dedicated servers!

If you prefer installing iceScrum on your own server, you can contact us to learn about our install services, which include custom configuration and remote installation.

Hardware requirements

Here is an estimated minimal server configuration:

  • Processor: a modern one, e.g. 2GHz+, 2+ cores
  • RAM: 2GB+ (iceScrum requires approximately 1GB, 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.)

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

Start iceScrum

First, download iceScrum:

Download icescrum.jar (7.54)

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 executable is accessible in your command line, type the following command to start iceScrum:

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

If you use Java 8, you can forget about the MaxPermSize setting and type this instead:

java -Xmx1024M -jar icescrum.jar

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=stringOrIP: Default: first external IP found, fallback to localhost which is limited to local access.
  • port=num: Default: 8080. Port to use for unsecure access (http). To use port 80, root privileges are required.
  • httpsPort=num: Default: nothing. Port used for secure access (https). To use port 443, root privileges are required.
  • context=string: Default: /icescrum. Defines the context part of the URL such as http://host:port/<context>. If you want no context like this: http://host:port/, set context=/.
  • workDir=directory: Default: java.io.tmpdir. Where the embedded Tomcat webapps and work directories are created.
  • enableAccessLog=bool: Default: false. If true, logs iceScrum HTTP access in a directory named access_logs in the .jar start path.

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

java -Xmx1024M -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. As a result, you will get an administrator account and the settings will be written in a file.

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:

Emojis support

Since iceScrum v7.8 we support emojis in iceScrum. It works on MySQL, PostgreSQL, SQL Server and H2. At the moment no support is provided for MSSQL.

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. 1 – Stop iceScrum
    1. 2 – Restart your MySQL server
    1. 3 – Start iceScrum
    1. 4 – Go to a textarea field and type “:” and verify that you have emojis suggestion list that shows up.
    1. 5 – Enjoy 😀

Custom URL / reverse proxy

It is common practice to use a reverse proxy (e.g. Apache or Nginx), 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) then a reverse proxy is not needed, use the options of the jar!

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

Troubleshooting

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

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. 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.
      1. 2 – Try to increase tomcat memory settings with an higher Xmx value.
      1. 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.


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