# Installation of OpenProject on Ubuntu 12.04

*Many thanks to Dan S. for the first draft of this guide.*

## Update and upgrade.

Update your system, so you know you have the latest available packages for your system.

apt-get update  
apt-get upgrade

## Install dependencies

Install git and curl.

apt-get install git curl

Install dependencies for our gems.

apt-get install build-essential libxslt-dev libxml2-dev libmysql-ruby libmysqlclient-dev libpq-dev libsqlite3-dev libyaml-0-2

Also install the following dependencies if you want to enable OpenProject to generate images (recommended):

apt-get install libmagickwand-dev libmagickcore-dev libmagickcore4-extra libgraphviz-dev libgvc5

You will need a database to run OpenProject. If you do not have a separate database server, install your favorite (MySQL or PostgreSQL) DBMS now.

For MySQL (please read [the ubuntu help](https://help.ubuntu.com/12.04/serverguide/mysql.html) for details and setup instructions):

sudo apt-get install mysql-server

For PostgreSQL (please read [the ubuntu help](https://help.ubuntu.com/community/PostgreSQL) for details and setup instructions):

sudo apt-get install postgresql

Install the <code>memcached</code> cache server (optional but recommended for production environments):

sudo apt-get install memcached

## Add openproject user and group.

It is recommented to have a separate user/group for OpenProject (at least for production systems). You may skip this step (and all further related steps) for your local development setup.

groupadd openproject  
useradd —create-home —gid openproject openproject  
passwd openproject \# (enter desired password)

We continue the setup as the `openproject` user. This way all directories are created with so that the `openproject` user can access them.

su openproject -c “bash -l”  
cd ~ \#or whatever directory you want to install openproject

## Install RVM (Ruby Version Manager)

A ruby version manager lets you deploy/use different ruby versions. It is installed in the users `$HOME` directory

\\curl -L https://get.rvm.io | bash -s stable  
source $HOME/.rvm/scripts/rvm

If you need help on how to install rvm, have a look at their homepage http://rvm.io .

## Use RVM to install Ruby

Ruby 2.1 is supported. Disable `rvm autolibs` so we don’t need admin privileges to install ruby (see [this StackOverflow question](http://stackoverflow.com/questions/16563115/how-to-install-rvm-system-requirements-without-giving-sudo-for-rvm-user) for details).

rvm autolibs disable  
rvm install 2.1.0

Install bundler.

gem install bundler

Make sure that

bundle —version

is `1.5.1` or higher. If you have an older bundler installed, upgrade the bundle gem.

## Clone the OpenProject repository.

git clone https://github.com/opf/openproject.git  
cd openproject  
git checkout stable

## Run bundler to install all gems

bundle install

or the following if you decided not to install `rmagick`

bundle install —without rmagick

## Configure your DBMS

You should create a database (MySQL or PostgreSQL) user with appropriate rights (create, remove, modify the openproject tables).

For MySQL:

CREATE DATABASE openproject CHARACTER SET utf8;  
CREATE USER ‘openproject’@`'localhost' IDENTIFIED BY 'my_password';
GRANT ALL PRIVILEGES ON openproject.* TO 'openproject'`@‘localhost’;

Also create the databases `openproject_development` and `openproject_test` and grant privileges on them if you are on a development machine.

For PostgreSQL:

CREATE ROLE openproject LOGIN ENCRYPTED PASSWORD ‘my\_password’ NOINHERIT VALID UNTIL ‘infinity’;  
CREATE DATABASE openproject WITH ENCODING=‘UTF8’ OWNER=openproject;

Also create the databases `openproject_development` and `openproject_test` and grant privileges on them if you are on a development machine.

Replace `my_password` with an appropriate password (avoid to use ‘\!’’ in the password).

## Configure OpenProject

Copy `config/database.yml.example` to `config/database.yml`.

cd config  
cp database.yml.example database.yml

Edit `database.yml` and fill in your database username and password.

Create an email account from which your OpenProject installation may send mails. You don’t need to do this for a development setup.  
We use a free gmail account in our example configuration.

Copy `config/configuration.yml.example` to `config/configuration.yml`.

cp configuration.yml.example configuration.yml

Edit the `default` key to look like this:

    # default configuration options for all environments
    default:
      # Outgoing emails configuration (see examples above)
      email_delivery:
        delivery_method: :smtp
        perform_deliveries: true
        smtp_settings:
          address: smtp.gmail.com
          port: 587
          enable_starttls_auto: true
          domain: "gmail.com" 
          authentication: :login
          user_name: "yourgmailaccountname”
          password: "yourpassword"

Note that the `enable_starttls_auto: true` line was added.

**Optional:** If you want to use the <code>memcached</code> cache server add the following line to the configuration (don’t forget to install <code>memcached</code> beforehand - see section 2 for details):

    rails_cache_store: :memcache

Create databases:

bundle exec rake db:create:all

Note: `bundle exec` helps to execute OpenProject with just those gems that were explicitly installed via `bundle install`. It is recommended to prepend `bundle exec` before every ruby oder gem invocation.

Run database migrations:

bundle exec rake db:migrate

Note: Per default the `development` environment is loaded. If you want to execute a command (like `bundle exec rake db:migrate` in the `production` environment, do `RAILS_ENV="production" bundle exec rake db:migrate`. the same applies to the `test` environment.)

Populate your database with example data. This is useful for development. In production systems, you probably want to configure OpenProject yourself (note that this also includes creating an admin account).

RAILS\_ENV=production bundle exec rake db:seed

In `development` mode the database is populated with a lot of sample usage data (some users, work packages, news, …) to simulate a lively OpenProject installation (grap a cup of coffee, this may take some time).

However, in `production` mode very few data is generated. Basically it’s just an admin account and some default types and roles.

Generate a secret token for the session store:

bundle exec rake generate\_secret\_token

## Install plugins (optional)

*For general information about OpenProject plug-ins refer to to the [plug-in page](https://www.openproject.org/projects/openproject/wiki/OpenProject_Plug-Ins.*)

Create a `Gemfile.plugins` file and add OpenProject plugins of your choice. In our example we install the `openproject-plugins` plugin (which adds a useful plugin generator so that you can start developing your custom plugin faster).

vi Gemfile.plugins  
gem “openproject-plugins”, “~\> 1.0.2”, :branch =\> ‘stable’

Run bundler to install the plugin gems:

bundle install

Read the gems `README` or installation instructions. Some gems need further configuration. Some gems even add migrations - you need to install them manually.

Please, make sure that the plugins version matches the core versions (if you use a current OpenProject ‘stable’ version, also use a current ‘stable’ version of your plugin).

## Start application server.

bundle exec rails server

You should now be able to access OpenProject at **`http://localhost:3000`**, where localhost is the IP address of the current machine.

The default administrator ID is **admin** and the password is **admin**.

## Further production setup

In a production system you probably want to set up

  - the [passenger gem](https://www.phusionpassenger.com/) (or use another rails deployment option)
  - precompile assets (`bundle exec rake assets:precompile`)
  - backups
  - init scripts
  - monitoring

For a production setup, we recommend to use the [[openproject:Mod\_security|mod\_security]] apache module (if you deploy with an apache webserver).