openproject/doc/development/setting-up-development-environment.md

OpenProject 5.x Development Setup on Debian 7.7

To develop OpenProject a setup similar to that for using OpenProject in production is needed. However, we can skip some parts of the installation guide, so that we can get up a development environment a little easier.

1. This guide requires that you have a clean Debian 7.7 x64 installation with administrative rights.
2. OpenProject will be installed with a MySQL database (the guide should work analogous with PostgreSQL).
3. OpenProject will be served in a development environment

If you find any bugs or you have any recommendations for improving this tutorial, please, feel free to comment in the OpenProject forums.

Prepare your environment

Install tools needed to compile Ruby and run OpenProject:

[dev@debian]# sudo apt-get update
[dev@debian]# sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-dev libmysqlclient-dev libpq-dev libsqlite3-dev memcached libffi6

Install Database (MySQL) packages

During installation, you have to enter a password for the mysql root-user.

[dev@debian]# sudo apt-get install mysql-server mysql-client

As a reference, we have installed the following MySQL version:

[dev@debian]# mysql --version
  mysql  Ver 14.14 Distrib 5.5.40, for debian-linux-gnu (x86_64) using readline 6.2

Create the OpenProject MySQL-user and database:

[dev@debian]# mysql -u root -p

You may replace the string “openproject” with the desired username and database-name. The password “my_password” should definitely be changed.

mysql> CREATE DATABASE openproject CHARACTER SET utf8;
mysql> CREATE USER 'openproject'@'localhost' IDENTIFIED BY 'my_password';
mysql> GRANT ALL PRIVILEGES ON openproject.* TO 'openproject'@'localhost';
mysql> \q

Install Node.js

We will install the latest 0.10.x version of Node.js via nodeenv:

[dev@debian]# sudo apt-get install python python-pip
[dev@debian]# sudo pip install nodeenv

Install Ruby

Switch to your development directory. In this guide we develop straight in the $HOME directory.

[user@debian]# cd ~

… and install RVM (Ruby Version Manager)

[dev@debian]# \curl -sSL https://get.rvm.io | bash -s stable
[dev@centos]# source $HOME/.rvm/scripts/rvm
[dev@debian]# export -f rvm_debug
[dev@debian]# rvm autolibs disable
[dev@debian]# rvm install 2.2.5
[dev@debian]# rvm use --default 2.2.5
[dev@debian]# gem install bundler

Activate Node.js

[dev@debian]# nodeenv nodeenv
[dev@debian]# source ./nodeenv/bin/activate
[dev@debian]# npm -g install bower

If the first step fails with OSError: Command make --jobs=2 failed with error code 2 try:

[dev@debian]# rm -r nodeenv
[dev@debian]# # for Ubuntu 12.04 virtualenv needed to be installed
[dev@debian]# sudo pip install virtualenv
[dev@debian]# virtualenv nodeenv
[dev@debian]# source ./nodeenv/bin/activate
[dev@debian]# pip install nodeenv
[dev@debian]# nodeenv -p --prebuilt
[dev@debian]# npm -g install bower

As a reference, the following Node.js and NPM versions have been installed on our system:

[dev@debian]# node --version
                      v6.2.2
[dev@debian]# npm --version
                      3.9.5
[dev@debian]# bower --version
                      1.7.9

Install OpenProject

[dev@debian]# git clone https://github.com/opf/openproject.git
[dev@debian]# cd openproject
[dev@debian]# bundle install
[dev@debian]# npm install
[dev@debian]# npm run webpack
[dev@debian]# cd frontend
[dev@debian]# bower install
[dev@debian]# cd ..

Note that we have checked out the dev branch of the OpenProject repository. Development in OpenProject happens in the dev branch (there is no master branch). So, if you want to develop a feature, create a feature branch from a current dev branch.

Configure OpenProject

Create and configure the database configuration file in config/database.yml (relative to the openproject-directory.

[dev@debian]# cp config/database.yml.example config/database.yml

Now edit the config/database.yml file and insert your database credentials. It should look like this (just with your database name, username, and password):

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

development:
  adapter: mysql2
  database: openproject
  host: localhost
  username: openproject
  password: openproject
  encoding: utf8

NOTE: You should validate the database.yml file, for example with http://www.yamllint.com/. YML-files are sensitive to whitespace — It is pretty easy to write invalid .yml files without seeing the error. Validating those files prevents you from such errors.

Finish the Installation of OpenProject

[dev@debian]# bundle exec rake db:create:all
[dev@debian]# bundle exec rake generate_secret_token
[dev@debian]# bundle exec rake db:migrate
[dev@debian]# bundle exec rake db:seed

The db:seed step is optional, but recommended. It creates many users, work packages, news etc. This takes some time, but gives you useful test data.

Run OpenProject as a Developer

You can start OpenProject with:

bundle exec rails server

Your OpenProject installation should be accessible on port 3000 (http). A default admin-account is created for you having the following credentials:

Username: admin
Password: admin

Start Coding

Please have a look at our development guidelines for tips and guides on how to start coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible. Also, take a look at the doc directory in our sources, especially the how to run tests documentation (we like to have automated tests for every new developed feature).

Troubleshooting

The OpenProject logfile can be found here:

/home/openproject/openproject/log/development.log

If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process).

Questions, Comments, and Feedback

If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the appropriate community.openproject.org forum. Follow OpenProject on twitter, and follow the news to stay up to date.