ChiliProject is not maintained anymore. Please be advised that there will be no more updates.

We do not recommend that you setup new ChiliProject instances and we urge all existing users to migrate their data to a maintained system, e.g. Redmine. We will provide a migration script later. In the meantime, you can use the instructions by Christian Daehn.

Installation of ChiliProject

Contents

ChiliProject should run on most systems as long as Ruby is available on this platform.

Which version to choose

It is recommended that you use the latest stable release of ChiliProject for production deployments. Although we work hard on keeping the whole code base stable, the master and unstable branches might break from time to time, so use them only if you are willing to engage very closely with the inner workings of ChiliProject.

Please refer to the release schedule for more information about existing and planned releases.

Requirements

Ruby

To begin with, you need to decide on a ruby interpreter. ChiliProject runs best on Ruby 1.8.7 and recent variants of Ruby Enterprise Edition. For a new system you should choose one of those. The default ruby 1.8.7 is available for most platforms while other ruby interpreters might work only on certain systems. Check the respective project website for more information.

Ruby Variant ChiliProject Version
current master >= 2.6.0 2.0.0 – 2.5.0 1.1.0 — Bell, — 1.5.0
1.8 1.8.7 1.8.7 1.8.7 1.8.6, 1.8.7
1.9 1.9.2, 1.9.3 1.9.2, 1.9.3 1.9.2 not supported
2.0 not supported not supported not supported not supported
Ruby Enterprise Edition 1.8.7-xxx 1.8.7-xxx 1.8.7-xxx 1.8.7-xxx
JRuby not supported not supported not supported not supported
Rubinius not supported not supported not supported not supported
IronRuby not supported not supported not supported not supported

Warning: Ruby 1.8.6 releases before p420 contain a XSS vulnerability in webrick. See CVE-2010-0541.

Support for Ruby 1.8.6 is deprecated in the 2.x series. If you would like to use Ruby 1.8.6 with 2.x, you may need to make modification to the application code and configuration. For new setups you are advised to use a Ruby 1.8.7 compatible interpreter.

Required Ruby Libraries

In addition to the basic ruby, you need some required libraries (called rubygems) which provide some of the core functionality offered by ChiliProject. Make sure your system has the exact versions of these components installed. If not specified otherwise the exact stated versions are required.

Requirement ChiliProject Version
current master >= 3.2.0 >= 2.0.0 1.2.0 – 1.5.0 1.1.0 — Bell
rubygems >= 1.3.7, < 2.0 >= 1.3.7, < 2.0 >= 1.3.7, < 2.0 >= 1.3.7, < 2.0 >= 1.3.7, <= 1.5.3
rails (managed by bundler) (managed by bundler) (managed by bundler) 2.3.5 2.3.5
rack (managed by bundler) (managed by bundler) (managed by bundler) 1.0.1 1.0.1
rake (managed by bundler) (managed by bundler) (managed by bundler) >= 0.8.3, <= 0.8.7 >= 0.8.3, <= 0.8.7
i18n (managed by bundler) (managed by bundler) (managed by bundler) 0.4.2 0.4.2
bundler >= 1.0.14 >= 1.0.14 >= 1.0.6 (not used) (not used)

Database

ChiliProject stores most of its working data inside a database. It supports each the following databases equally well. Choose the one that fits your needs the most.

  • MySQL 5.x
  • PostgreSQL 8.x and 9.x
  • SQLite3

(Making ChiliProject work with Oracle is not impossible, but needs some work, see rob glazers forum post for more details)

For most production deployments, you should choose one of MySQL or PostgreSQL as these are going to be much more performant. For small and sparsely used installations SQLite3 is also sufficient. To later migrate between databases vendors, you can use Taps, YamlDb, or some other database agnostic tool.

To connect ChiliProject to the chosen database you need an additional ruby gem which acts as an adapter. For some databases, there are different libraries available and used. As some of the adapters are not maintained anymore you are advised to use one of the preferred gems from the following table. Preferred database adapters are marked with a star ( ).

Requirement ChiliProject Version
current master >= 2.0.0 1.1.0 — Bell, 1.2.0, 1.3.0, 1.4.0, 1.5.0
MySQL mysql (see notes) all versions all versions all versions
mysql2 (see notes) all versions all versions all versions
ruby-mysql (pure ruby version) ??? ??? ???
PostgreSQL pg all versions all versions all versions
postgres-pr (pure ruby version) all versions all versions all versions
SQLite3 sqlite3-ruby all versions all versions all versions

The mysql gem exposes a bug in newer releases of Ruby 1.8.6. In order to make it work, you should either use a Ruby version older than or equal to 1.8.6-p388 or a mysql gem version older than or equal to 2.7. Generally, you are advised to run Ruby 1.8.7 if possible.

The mysql database adapter is only available for Ruby 1.8 as it doesn't properly observe string encoding requirements in Ruby 1.9. On Ruby 1.9, please use the mysql2 adapter instead. It provides the same functionality and is even a bit faster.

ChiliProject 1.x note: Please be aware, that Rails 2.3.5 (used in ChiliProject 1.x) has some special handling for the mysql gem. This results in limited functionality for the mysql2 gem. Therefor you will not able to properly execute the following rake tasks:

  • db:create and db:create:all
  • db:drop and db:drop:all
  • db:test:prepare

This should not be an issue in production environments. Also, these issues are fixed with ChiliProject 2.0, with Rails 2.3.12, which solves the above mentioned limitations.

Application Server

Every Ruby on Rails application runs in an environment called application server. These server components which provide the basic HTTP functionality. There are various choices which heavily depend on your operating system end environmental constraints. See the installation guide of your specific operating system for more information.

The most common choices for production deployments are Phusion Passenger (mod_rails) for Linux / UNIX which is a module for the Apache2 or Nginx webserver or Thin on Windows. Although Rails comes with a basic application server called Webrick it is only suitable for development and tests. Never use Webrick in production deployments!

Optional Components

You need some additional software depending on your use-case. For a basic ChiliProject, these components are optional, but might be required for some additional functionality.

Optional Component Description
SCM binaries ChiliProject requires the client binaries for each of the repository types you plan to use. See Repository Administration for more info.
RMagick This gem is the ruby interface to ImageMagick. It is used to export the Gantt charts to PNG format.
ruby-openid This gem is required for using the OpenID authentication. Version 2 or greater is required.

Installation

  1. Get the ChiliProject source code by either downloading a packaged release or checking out the code repository. Common sources are
  2. Install the required gems using bundler
    • Install Ruby dependencies by running the following command in the root directory of ChiliProject. This will download and check that all of the required rubygems are installed.
      bundle install --without test development
      Not all dependencies are required, especially not all database adapters. See our documentation for setting up bundler and chose the settings that are appropriate for you.
  3. Create an empty database and an accompanying user named chiliproject for example.
    • MySQL < 5.0.2
      create database chiliproject character set utf8;
      grant all privileges on chiliproject.* to 'chiliproject'@'localhost' identified by 'my_password';
      
    • MySQL >= 5.0.2
      create database chiliproject character set utf8;
      create user 'chiliproject'@'localhost' identified by 'my_password';
      grant all privileges on chiliproject.* to 'chiliproject'@'localhost';
      
    • PostgreSQL
      CREATE ROLE chiliproject LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
      CREATE DATABASE chiliproject WITH ENCODING='UTF8' OWNER=chiliproject;
      
  4. Copy config/database.yml.example to config/database.yml and edit this file in order to configure your database settings for "production" environment. Valid examples are:
    • MySQL
      Depending on your chosen adapter in step 2, you have to either enter mysql or mysql2 as the adapter name.
      production:
        adapter: mysql
        database: chiliproject
        host: localhost
        port: 3306
        username: chiliproject
        password: my_password
      
    • PostgreSQL
      production:
        adapter: postgresql
        database: chiliproject
        host: localhost
        port: 5432
        username: chiliproject
        password: my_password
        encoding: utf8
      
    • SQLite
      production:
        adapter: sqlite3
        database: db/production.db
      
  5. Copy config/configuration.yml.example to config/configuration.yml and edit this file for your system's environment. You can check the comments in the file and on Configuration File for all of the options.
  6. Generate a session store secret.
    bundle exec rake generate_session_store
  7. Create the basic database structure by running the following command under the application root directory:
    RAILS_ENV=production bundle exec rake db:migrate
    
    It will create the database tables and an administrator account.
  8. Insert default configuration data into the database, by running the following command:
    RAILS_ENV=production bundle exec rake redmine:load_default_data
    
    This step is optional but highly recommended. It will load default roles, trackers, statuses, workflows and enumerations. If you choose to skip this step, you can later define your own configuration from scratch.
  9. Setting up permissions
    Windows users have to skip this step
    The user who runs ChiliProject must have write permission on the following sub-directories: files, log, tmp, and public/plugin_assets. So assuming you run ChiliProject with a user called chiliproject you need to setup the following permissions:
    mkdir -p tmp public/plugin_assets
    sudo chown -R chiliproject:chiliproject files log tmp public/plugin_assets
    sudo chmod -R 755 files log tmp public/plugin_assets
    
  10. Test the installation by running the bundled Webrick web server:
    bundle exec script/server -e production
    

    Windows users have to specify to use ruby:
    bundle exec ruby script/server -e production
    

    Once Webrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
    Webrick is not suitable for normal use, please only use Webrick for testing that the installation up to this point is functional. It is not recommended to use Webrick for anything other than development or testing. Use one of the many other guides in this wiki to setup ChiliProject with a real application server like Phusion Passenger (mod_rails), Unicorn, or Thin.
  11. Use the default administrator account to log in:
    • Login: admin
    • Password: admin
  12. You can now go to Administration to modify the basic application settings. Have a look at the user guide for information on how to configure your new ChiliProject server.