Installation on Ubuntu 11 04 (Natty Narwhal)¶

Contents

• Installation on Ubuntu 11 04 (Natty Narwhal)
  • Ubuntu setup
  • Global dependencies and basic system setup
  • Install Apache, Ruby and basic dependencies
  • Install Bundle
  • Configure the database
    • Configure MySQL
    • Configure PostgreSQL
  • Install ChiliProject
    • Download and checkout ChiliProject
    • Use Bundle to install all required Gems.
    • Configure ChiliProject to use your database
      • MySQL
    • Configure ChiliProject for your environment
    • Generate a session store secret.
    • Generate a generic database structure
    • Preload Default Configuration Data
    • Setting up permissions
  • Setup Apache2 with Passenger
  • Setup the Apache virtual host

This guide is written and tested for ChiliProject version 2.0.0, using Ubuntu Server 11.04, with no packages selected during installation. Changes to Ubuntu's software repository (accessed with apt- commands) may cause parts of this guide to become dated. In other words, your mileage may vary (YMMV).

All commands mentioned here are assumed to be run as root. Many of them will not work when run as a normal user. You can get a root shell by running sudo -s.

Ubuntu setup¶

As depicted above, this install is assuming a vanilla Ubuntu Server install, with no other packages chosen for installation. If you chose a different route during your installation of Ubuntu, you may find that you already have packages installed that we list below.

Global dependencies and basic system setup¶

mkdir -p /var/www/chiliproject
adduser --system --home /var/www/chiliproject --group --shell /bin/sh --disabled-login chiliproject

Install Apache, Ruby and basic dependencies¶

apt-get update
apt-get install apache2 ruby rubygems build-essential curl git subversion apache2-mpm-prefork mysql-server mysql-client
apt-get install libopenssl-ruby1.8 libmysqlclient-dev libpq-dev libsqlite3-dev libssl-dev zlib1g-dev libreadline5-dev libxml2-dev libapache2-mod-passenger libmagick9-dev

Install Bundle¶

ChiliProject can use bundler to install and verify all the gems required for ChilProject to function properly.

gem install bundler

Configure the database¶

ChiliProject supports MySQL, PostgreSQL and SQLite3. For a production environment, you should go with either MySQL or PostgreSQL to prevent scaling and issues and problems from parallel access to the SQLite database. The following sections discuss the creation of a MySQL or PostgreSQL database, one of the two should be followed.

Configure MySQL¶

When running apt-get earlier, you were prompted to provide a root password for MySQL. That password should be as secure as, if not more than, the admin password for the server itself, and good practice says it should be different from the password you're going to use for the chiliproject account. The following command, mysql -uroot -p starts the mysql client and has it log into the locally running instance for you. You will need to provide the password you set at that time.

mysql -uroot -p

The following set of commands will set up the chiliproject database inside of MySQL 5.1, as well as creating the user ChiliProject will use, and establishing permissions for that user.

create database chiliproject character set utf8;
create user 'chiliproject'@'localhost' identified by 'my_password';
grant all privileges on chiliproject.* to 'chiliproject'@'localhost';
exit

For a single-system setup, the basic Ubuntu configuration is sufficient. For a real production setup you might want to tune your MySQL server a bit. The default configuration is targeted at very small systems. Query handling times can be improved by properly tuning your MySQL depending on your hardware. As always, YMMV, and a plethora of guides can be found elsewhere online regarding performance tuning MySQL.

Configure PostgreSQL¶

The simplest way to run psql to create the database is to become "root" and run the psql database creation command as the PostgreSQL user.

sudo -u postgres psql -f config/createdb.psql

Contents of config/createdb.psq (modify as appropriate). The file needs to be owned by the postgres user and should have restricted permissions (e.g. go-rwx) because it contains the database password.

CREATE ROLE chiliproject LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE chiliproject WITH ENCODING='UTF8' OWNER=chiliproject;

Install ChiliProject¶

Download and checkout ChiliProject¶

cd /var/www/chiliproject/
git clone git://github.com/chiliproject/chiliproject.git
cd chiliproject
git checkout stable

Use Bundle to install all required Gems.¶

Note: if you try to run bundle on the console and get command not found, you'll need to add gems' binary directory to your PATH:

export PATH=$PATH:$HOME/bin:/var/lib/gems/1.8/bin
bundle install

Configure ChiliProject to use your database¶

Copy config/database.yml.example to config/database.yml and edit it.

• "my_password" should match the password supplied in the database configuration mentioned above.

MySQL¶

production:
  adapter: mysql
  database: chiliproject
  host: localhost
  port: 3306 # (not needed for socket connection)
  username: chiliproject
  password: my_password
  encoding: utf8

PostgreSQL

production:
  adapter: postgresql
  database: chiliproject3
  host: localhost
  username: chiliproject
  password: "my_password" 

Configure ChiliProject for your environment¶

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.

cp config/configuration.yml.example config/configuration.yml

Generate a session store secret.¶

bundle exec rake generate_session_store

Generate a generic database structure¶

Create the basic database structure by running the following command under the application root directory:

RAILS_ENV=production rake db:migrate

It will create the database tables and an administrator account.

Preload Default Configuration Data¶

Insert default configuration data into the database, by running the following command:

RAILS_ENV=production 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.

Setting up permissions¶

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:

sudo chown -R chiliproject:chiliproject files log tmp public/plugin_assets
sudo chmod -R 755 files log tmp public/plugin_assets

Setup Apache2 with Passenger¶

Edit /etc/apache2/mods-enabled/passenger.conf to force it to use our chiliproject user. Add the PassengerDefaultUser chiliproject directive. In the end, the file should look like this:

<IfModule mod_passenger.c>
  PassengerRoot /usr
  PassengerRuby /usr/bin/ruby

  PassengerDefaultUser chiliproject
</IfModule>

Finally enable the module (it probably already is though) and reload Apache.

a2enmod passenger
/etc/init.d/apache2 reload

Setup the Apache virtual host¶

In this tutorial we're going to set up Apache to serve ChiliProject from the root of the site. If you need to install ChiliProject on a server hosting multiple sites (using Apache's Virtual Hosts) you'll need to adapt accordingly. For getting SSL up and going, see [Using SSL on Ubuntu 11.04]

/etc/apache2/sites-available/chiliproject

<VirtualHost _default_:80>
    ServerAdmin webmaster@localhost

    DocumentRoot /var/www/chiliproject/chiliproject/public
    <Directory /var/www/chiliproject/chiliproject/public>
           Options FollowSymLinks
           AllowOverride None
           Order deny,allow
           Allow from all
    </Directory>

    ErrorLog /var/log/apache2/error.log

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    CustomLog /var/log/apache2/chiliproject.log combined
</VirtualHost>

Now activate the new virtual host and reload Apache. ChiliProject will be started at the first request to your server.

a2dissite default
a2ensite chiliproject
/etc/init.d/apache2 reload