Install and configure

This documentation applies only to iceScrum v7. If you really want to install iceScrum R6, which will be deprecated soon, click here.

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

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

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.1.0)

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 -Xmx512M -XX:MaxPermSize=256m -jar icescrum.jar

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

java -Xmx512M -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=value: Defaults to the first external IP found or falls back 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=/

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. 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, PostgreSQL, MS SQL Server or Oracle. If you do so, create and empty database for iceScrum, usually named icescrum, with a proper charset/collation, we strongly recommend UTF-8.

Here is how to create the empty database on MYSQL:

CREATE DATABASE `icescrum` CHARACTER SET utf8 COLLATE utf8_general_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
  • 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 (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:

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 Pro Standalone comes with dedicated support (email, skype, phone).

Common questions / issues

HTTPS
If you want to use iceScrum with the HTTPS protocol and if you use a reverse proxy to manage the SSL part of it, then you should rather install iceScrum the old fashioned way with a Tomcat server: install iceScrum on Tomcat.

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

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.