OpenProject is an open source project management software. It’s a web-based system that runs in your browser and is built on Ruby on Rails. What makes it really worth-wile is a wide set of features and plugins and a very active and always helpful community.

0. Installation prerequisites

To run OpenProject, you’ll need a working Database (either MySQL 5.x or PostgreSQL 8.x) and a method of deploying a Ruby on Rails application. For example, this could be nginx, an Apache server or the small web server named WEBrick that comes with Ruby. In this example, we’ll use Apache with Phusion Passenger and a MySQL database.

So here’s a one-liner to install all required packages at once:

# yum install git mariadb-server httpd rubygem-bundler ruby-devel gcc \
libxml2-devel libxslt-devel gcc-c++ mariadb-devel ruby-RMagick \
ImageMagick-devel sqlite-devel libcurl-devel httpd-devel apr-devel \
apr-util-devel

1. Setting up the database

Let’s create a new database user called openproject and grant him all privileges on a new database also called openproject:

$ mysql --user=root --password
Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 11
Server version: 5.5.34-MariaDB MariaDB Server

Copyright (c) 2000, 2013, Oracle, Monty Program Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> CREATE USER 'openproject'@'localhost' IDENTIFIED BY 'password';
Query OK, 0 rows affected (0.00 sec)

MariaDB [(none)]> CREATE SCHEMA openproject CHARACTER SET utf8;
Query OK, 1 row affected (0.00 sec)

MariaDB [(none)]> GRANT ALL PRIVILEGES ON openproject.* TO 'openproject'@'localhost';
Query OK, 0 rows affected (0.00 sec)

MariaDB [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.00 sec)

MariaDB [(none)]> quit
Bye

2. Install and configure OpenProject

Clone the OpenProject repository

Since OpenProject 3.0 is still in development, there’s no release tarball yet. We have to clone the git repository instead:

# cd /var/www/html/
# git clone https://github.com/opf/openproject.git
   Cloning into 'openproject'...
   remote: Reusing existing pack: 114407, done.
   remote: Counting objects: 404, done.
   remote: Compressing objects: 100% (268/268), done.
   remote: Total 114811 (delta 208), reused 315 (delta 119)
   Receiving objects: 100% (114811/114811), 34.69 MiB | 3.57 MiB/s, done.
   Resolving deltas: 100% (81636/81636), done.
   Checking connectivity... done
# cd openproject/

Install gems

# cd /var/www/html/openproject
# bundle install --without postgres

Configure config/database.yml

There’s a sample configuration file at config/database.yml.example we can use. Simply make a copy and change the username and password:

# cp config/database.yml.example config/database.yml

Open config/database.yml with you favourite editor and change username and password:

[...]
production:
  adapter: mysql2
  database: openproject
  host: localhost
  username: openproject
  password: password
  encoding: utf8
[...]

Configure config/configuration.yml

Again, there’s a samle in the config folder.

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

You don’t really have to make any changes to the sample configuration file but you might want to look into the section, that’s labelled Outgoing emails configuration to configure your smtp server for email notifications.

Optional:
It’s usually a good idea to enable memchache. Open the config/configuration.yml and uncomment the memcache option.

[...]
  # use memcache for performance, memcached must be installed
  rails_cache_store: :memcache
[...]

To install and enable memcached run

# yum -y install memcached
# systemctl enable memcached.service 
ln -s '/usr/lib/systemd/system/memcached.service' '/etc/systemd/system/multi-user.target.wants/memcached.service'
# systemctl start memcached.service

Run database migrations and seeds

This will create the default database structure and create some initial data, like an admin user:

$ RAILS_ENV="production" bundle exec rake db:migrate db:seed
[...]

Generate a secret token for the session store

# RAILS_ENV="production" bundle exec rake generate_secret_token
require 'rails/all'... 0.750s
Bundler.require... 2.040s

Precompile assets

Because Rails usually reloads most of the OpenProject codebase at every request and compiles the corresponding asset, page requests are answered very slowly in the development environment. In a production environment though, we can precompile all assets since the codebase rarely changes, which will speed up page requests significantly:

# RAILS_ENV="production" bundle exec rake assets:precompile
[...]

3. Deploy

Just a quick note: If you want to deply OpenProject via WEBrick you’ll have to enable Rails’s own static asset server, since this would normally be done by Apache or ngix

[...]
  # Disable Rails's static asset server (Apache or nginx will already do this)
  config.serve_static_assets = true
[...]

If you deploy OpenProject via Apache or ngix, leave the static asset server disable (config.serve_static_assets = false).

To start WEBrick, run

# RAILS_ENV="production" rails s
require 'rails/all'... 0.690s
Bundler.require... 2.140s
=> Booting Thin
=> Rails 3.2.16 application starting in production on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server
8.170s
>> Thin web server (v1.5.1 codename Straight Razor)
>> Maximum connections set to 1024
>> Listening on 0.0.0.0:3000, CTRL+C to stop

Deploying with Phusion Passenger

First, install the passenger gem:

# cd /var/www/html/openproject
# gem install passenger
Fetching: daemon_controller-1.1.8.gem (100%)
Successfully installed daemon_controller-1.1.8
Fetching: passenger-4.0.33.gem (100%)
Building native extensions.  This could take a while...
Successfully installed passenger-4.0.33
Parsing documentation for daemon_controller-1.1.8
Installing ri documentation for daemon_controller-1.1.8
Parsing documentation for passenger-4.0.33
Installing ri documentation for passenger-4.0.33
Done installing documentation for daemon_controller, passenger after 27 seconds
2 gems installed

After that’s done, run the passenger-install-apache2-module script, which will compile the passenger module.

# passenger-install-apache2-module
[...]

Configure Apache

After the compilation is done, the script even tells us, how to install mod_passenger and how to set up the apache vhost:

[...]
The Apache 2 module was successfully installed.

Please edit your Apache configuration file, and add these lines:

   LoadModule passenger_module /usr/local/share/gems/gems/passenger-4.0.33/buildout/apache2/mod_passenger.so
   PassengerRoot /usr/local/share/gems/gems/passenger-4.0.33
   PassengerDefaultRuby /usr/bin/ruby

After you restart Apache, you are ready to deploy any number of web
applications on Apache, with a minimum amount of configuration!

Press ENTER to continue.


--------------------------------------------

Deploying a web application: an example

Suppose you have a web application in /somewhere. Add a virtual host to your
Apache configuration file and set its DocumentRoot to /somewhere/public:

   <VirtualHost *:80>
      ServerName www.yourhost.com
      # !!! Be sure to point DocumentRoot to 'public'!
      DocumentRoot /somewhere/public    
      <Directory /somewhere/public>
         # This relaxes Apache security settings.
         AllowOverride all
         # MultiViews must be turned off.
         Options -MultiViews
      </Directory>
   </VirtualHost>

And that's it! You may also want to check the Users Guide for security and
optimization tips, troubleshooting and other useful information:

  /usr/local/share/gems/gems/passenger-4.0.33/doc/Users guide Apache.html
  http://www.modrails.com/documentation/Users%20guide%20Apache.html

Enjoy Phusion Passenger, a product of Phusion (www.phusion.nl) :-)
https://www.phusionpassenger.com

Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.

To install mod_passenger we create a file called /etc/httpd/conf.modules.d/passenger.conf with the following content:

   LoadModule passenger_module /usr/local/share/gems/gems/passenger-4.0.33/buildout/apache2/mod_passenger.so
   PassengerRoot /usr/local/share/gems/gems/passenger-4.0.33
   PassengerDefaultRuby /usr/bin/ruby

Before starting up Apache, we need a vhost for OpenProject

<VirtualHost *:80>
    ServerName OpenProject
    DocumentRoot /var/www/html/openproject/public
    RailsEnv production
    PassengerDefaultUser root
    <Directory /var/www/html/openproject/public>
       # This relaxes Apache security settings.
       AllowOverride all
       # MultiViews must be turned off.
       Options -MultiViews
    </Directory>
</VirtualHost>

Start up Apache and point your webbrowser to http://OpenProject.

# systemctl enable httpd.service 
ln -s '/usr/lib/systemd/system/httpd.service' '/etc/systemd/system/multi-user.target.wants/httpd.service'
# systemctl start httpd.service

The Default administrator account is

Login: admin
Password: admin