To develop OpenProject a setup similar to that for using OpenProject in production is needed.
This guide assumes that you have a Ubuntu 18.04 installation with administrative rights. This guide will work analogous with all other distributions, but may require slight changes in the required packages. Please, help us to extend this guide with information on other distributions should there be required changes.
OpenProject will be installed with a PostgreSQL database.
Please note: This guide is NOT suitable for a production setup, but only for developing with it!
If you find any bugs or you have any recommendations for improving this tutorial, please, feel free to send a pull request or comment in the OpenProject forums.
We need an active Ruby and Node JS environment to run OpenProject. To this end, we need some packages installed on the system.o
sudo apt-get update sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-dev libpq-dev libreadline-dev
Use rbenv and ruby-build to install Ruby. We always require the latest ruby versions, and you can check which version is required by checking the Gemfile for the
ruby "~> X.Y" statement. At the time of writing, this version is “2.7”
rbenv is a ruby version manager that lets you quickly switch between ruby versions. ruby-build is an addon to rbenv that installs ruby versions.
# Install rbenv locally for the dev user git clone https://github.com/rbenv/rbenv.git ~/.rbenv # Optional: Compile bash extensions cd ~/.rbenv && src/configure && make -C src # Add rbenv to the shell's $PATH. echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc # Run rbenv-init and follow the instructions to initialize rbenv on any shell ~/.rbenv/bin/rbenv init # Source bashrc source ~/.bashrc
ruby-build is an addon to rbenv that installs ruby versions
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
With both installed, we can now install the actual ruby version 2.7. You can check available ruby versions with
rbenv install --list. At the time of this writing, the latest stable version is
2.7.3, which we also require.
We suggest you install the version we require in the Gemfile. Search for the
ruby '~> X.Y.Z' line and install that version.
# Install the required version as read from the Gemfile rbenv install 2.7.3
This might take a while depending on whether ruby is built from source. After it is complete, you need to tell rbenv to globally activate this version
rbenv global 2.7.3 rbenv rehash
You also need to install bundler, the ruby gem bundler.
gem install bundler
If you get
Command 'gem' not found... here, ensure you followed the instructions
rbenv init command to ensure it is loaded in your shell.
Next, install a PostgreSQL database.
[dev@debian]# sudo apt-get install postgresql postgresql-client
Create the OpenProject database user and accompanied database.
sudo su postgres [postgres@ubuntu]# createuser -d -P openproject
You will be prompted for a password, for the remainder of these instructions, we assume its
Now, create the database
openproject_test owned by the previously created user.
[postgres@ubuntu]# createdb -O openproject openproject_dev [postgres@ubuntu]# createdb -O openproject openproject_test # Exit the shell as postgres [postgres@ubuntu]# exit
We will install the latest LTS version of Node.js via nodenv. This is basically the same steps as for rbenv:
# Install nodenv git clone https://github.com/nodenv/nodenv.git ~/.nodenv # Optional: Install bash extensions cd ~/.nodenv && src/configure && make -C src # Add nodenv to the shell's $PATH. echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.bashrc # Run nodenv init and follow the instructions to initialize nodenv on any shell ~/.nodenv/bin/nodenv init # Source bashrc source ~/.bashrc
git clone https://github.com/nodenv/node-build.git $(nodenv root)/plugins/node-build
You can find the latest LTS version here: https://nodejs.org/en/download/
At the time of writing this is v14.17.0 Install and activate it with:
nodenv install 14.17.0 nodenv global 14.17.0 nodenv rehash
npm install npm@latest -g
You should now have an active ruby and node installation. Verify that it works with these commands.
ruby --version ruby 2.7.3p183 (2021-04-05 revision 6847ee089d) [x86_64-linux]] bundler --version Bundler version 2.1.4 node --version v14.16.1 npm --version 7.15.1
In order to create a pull request to the core OpenProject repository, you will want to fork it to your own GitHub account. This allows you to create branches and push changes and finally opening a pull request for us to review.
To do that, go to https://github.com/opf/openproject and press “Fork” on the upper right corner.
# Download the repository # If you want to create a pull request, replace the URL with your own fork as described above git clone https://github.com/opf/openproject.git cd openproject
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
Create and configure the database configuration file in
config/database.yml (relative to the openproject-directory.
[dev@debian]# vim 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):
default: &default adapter: postgresql encoding: unicode host: localhost username: openproject password: openproject-dev-password development: <<: *default database: openproject_dev test: <<: *default database: openproject_test
Install code dependencies, link plugin modules and export translation files.
- gem dependencies (If you get errors here, you’re likely missing a development dependency for your distribution)
- link plugin frontend modules
- and export frontend localization files
Now, run the following tasks to seed the dev database, and prepare the test setup for running tests locally.
RAILS_ENV=development bin/rails db:seed
You can run all required workers of OpenProject through
foreman, which combines them in a single tab. This is useful for starting out, however most developers end up running the tasks in separate shells for better understanding of the log output, since foreman will combine all of them.
gem install foreman foreman start -f Procfile.dev
The application will be available at
http://127.0.0.1:3000. To customize bind address and port copy the
.env.example provided in the root of this project as
.env and configure values as required.
By default a worker process will also be started. In development asynchronous execution of long-running background tasks (sending emails, copying projects, etc.) may be of limited use. To disable the worker process:
echo “concurrency: web=1,assets=1,worker=0” » .foreman
For more information refer to Foreman documentation section on default options.
You can access the application with the admin-account having the following credentials:
Username: admin Password: admin
To run OpenProject manually, you need to run the rails server and the webpack frontend bundler to:
RAILS_ENV=development ./bin/rails server
This will start the development server on port
3000 by default.
To run the frontend server, please run
RAILS_ENV=development npm run serve
This will watch for any changes within the
You can then access the application either through
localhost:3000 (Rails server) or through the frontend proxied
http://localhost:4200, which will provide hot reloading for changed frontend code.
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).
The OpenProject logfile can be found in
If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process).
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.