kanbanworkflowstimelinescrumrubyroadmapproject-planningproject-managementopenprojectangularissue-trackerifcgantt-chartganttbug-trackerboardsbcf
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
292 lines
10 KiB
292 lines
10 KiB
# OpenProject development Setup on Debian / Ubuntu
|
|
|
|
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](https://community.openproject.org/projects/openproject/boards).
|
|
|
|
# Prepare your environment
|
|
|
|
We need an active Ruby and Node JS environment to run OpenProject. To this end, we need some packages installed on the system.o
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-dev libpq-dev libreadline-dev
|
|
```
|
|
|
|
## Install Ruby
|
|
|
|
Use [rbenv](https://github.com/rbenv/rbenv) and [ruby-build](https://github.com/rbenv/ruby-build#readme) to install Ruby. We always require the latest ruby versions, and you can check which version is required by [checking the Gemfile](https://github.com/opf/openproject/blob/dev/Gemfile#L31) for the `ruby "~> X.Y"` statement. At the time of writing, this version is "2.7"
|
|
|
|
**Install rbenv and ruby-build**
|
|
|
|
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.
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
**Installing ruby-build**
|
|
|
|
ruby-build is an addon to rbenv that installs ruby versions
|
|
|
|
```bash
|
|
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
|
|
```
|
|
|
|
**Installing ruby-2.7**
|
|
|
|
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](https://github.com/opf/openproject/blob/dev/Gemfile). Search for the `ruby '~> X.Y.Z'` line
|
|
and install that version.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
rbenv global 2.7.3
|
|
rbenv rehash
|
|
```
|
|
|
|
You also need to install [bundler](https://github.com/bundler/bundler/), the ruby gem bundler.
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Setup PostgreSQL database
|
|
|
|
Next, install a PostgreSQL database.
|
|
|
|
```bash
|
|
[dev@debian]# sudo apt-get install postgresql postgresql-client
|
|
```
|
|
|
|
Create the OpenProject database user and accompanied database.
|
|
|
|
```bash
|
|
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 `openproject-dev-password`.
|
|
|
|
Now, create the database `openproject_dev` and `openproject_test` owned by the previously created user.
|
|
|
|
```bash
|
|
[postgres@ubuntu]# createdb -O openproject openproject_dev
|
|
[postgres@ubuntu]# createdb -O openproject openproject_test
|
|
|
|
# Exit the shell as postgres
|
|
[postgres@ubuntu]# exit
|
|
```
|
|
|
|
## Install Node.js
|
|
|
|
We will install the latest LTS version of Node.js via [nodenv](https://github.com/nodenv/nodenv). This is basically the same steps as for rbenv:
|
|
|
|
**Install nodenv**
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
**Install node-build**
|
|
|
|
```bash
|
|
git clone https://github.com/nodenv/node-build.git $(nodenv root)/plugins/node-build
|
|
```
|
|
|
|
**Install latest LTS node version**
|
|
|
|
You can find the latest LTS version here: https://nodejs.org/en/download/
|
|
|
|
At the time of writing this is v14.16.1 Install and activate it with:
|
|
|
|
```bash
|
|
nodenv install 14.16.1
|
|
nodenv global 14.16.1
|
|
nodenv rehash
|
|
```
|
|
|
|
## Verify your installation
|
|
|
|
You should now have an active ruby and node installation. Verify that it works with these commands.
|
|
|
|
```bash
|
|
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.11.2
|
|
```
|
|
|
|
# Install OpenProject
|
|
|
|
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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
# Install
|
|
# - gem dependencies (If you get errors here, you're likely missing a development dependency for your distribution)
|
|
# - node_modules
|
|
# - link plugin frontend modules
|
|
# - and export frontend local files
|
|
bin/setup_dev
|
|
```
|
|
|
|
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.
|
|
|
|
```bash
|
|
[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
|
|
```
|
|
|
|
## Finish the Installation of OpenProject
|
|
|
|
Now, run the following tasks to migrate and seed the dev database, and prepare the test setup for running tests locally.
|
|
|
|
```bash
|
|
RAILS_ENV=development bin/rails db:migrate
|
|
RAILS_ENV=development bin/rails db:seed
|
|
```
|
|
|
|
|
|
## Run OpenProject through foreman
|
|
|
|
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.
|
|
|
|
```bash
|
|
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][foreman-env] 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][foreman-defaults].
|
|
|
|
You can access the application with the admin-account having the following credentials:
|
|
|
|
Username: admin
|
|
Password: admin
|
|
|
|
## Run OpenProject manually
|
|
|
|
To run OpenProject manually, you need to run the rails server and the webpack frontend bundler to:
|
|
|
|
**Rails web server**
|
|
|
|
```bash
|
|
RAILS_ENV=development ./bin/rails server
|
|
```
|
|
|
|
This will start the development server on port `3000` by default.
|
|
|
|
**Angular frontend**
|
|
|
|
To run the frontend server, please run
|
|
|
|
```bash
|
|
RAILS_ENV=development npm run serve
|
|
```
|
|
|
|
This will watch for any changes within the `frontend/` and compile the application javascript bundle on demand. You will need to watch this tab for the compilation output,
|
|
should you be working on the TypeScript / Angular frontend part.
|
|
|
|
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.
|
|
|
|
## Start Coding
|
|
|
|
Please have a look at [our development guidelines](https://www.openproject.org/open-source/code-contributions/) 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](https://github.com/opf/openproject/blob/dev/docs/development/running-tests/README.md) documentation (we like to have automated tests for every new developed feature).
|
|
|
|
## Troubleshooting
|
|
|
|
The OpenProject logfile can be found in `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](https://community.openproject.org/projects/openproject/boards/9).
|
|
[Follow OpenProject on twitter](https://twitter.com/openproject), and follow [the news](https://www.openproject.org/blog) to stay up to date.
|
|
|
|
[foreman-defaults]:http://ddollar.github.io/foreman/#DEFAULT-OPTIONS
|
|
[foreman-env]:http://ddollar.github.io/foreman/#ENVIRONMENT
|
|
|