Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update expected node and npm versions on development setup instructions #15105

Merged
merged 2 commits into from
Mar 26, 2024
Merged

Update expected node and npm versions on development setup instructions #15105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9934d8
Update node and npm versions expected
aaron-contreras Mar 25, 2024
2b45ecc
Fix typo in description.
dombesz Mar 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 61 additions & 27 deletions docs/development/development-environment-osx/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,20 @@ 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).
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'll use [homebrew](https://brew.sh/) to install most of our requirements. Please install that first using the guide on their homepage.
We'll use [homebrew](https://brew.sh/) to install most of our requirements. Please install that first using the guide on
their homepage.

## 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 "3.2.3"
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 "3.2.3"

### Install rbenv and ruby-build

Expand All @@ -38,18 +43,21 @@ $ rbenv init

### Installing ruby

With both installed, we can now install the actual ruby version. You can check available ruby versions with `rbenv install --list`.
With both installed, we can now install the actual ruby version. You can check available ruby versions
with `rbenv install --list`.
At the time of this writing, the latest stable version is `3.2.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
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.

```shell
# Install the required version as read from the Gemfile
rbenv install 3.2.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
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

```shell
rbenv global 3.2.3
Expand All @@ -63,7 +71,8 @@ gem install bundler

## Setup PostgreSQL database

Next, install a PostgreSQL database. If you wish to use a MySQL database instead and have installed one, skip these steps.
Next, install a PostgreSQL database. If you wish to use a MySQL database instead and have installed one, skip these
steps.

```shell
# Install postgres database
Expand All @@ -78,6 +87,7 @@ Then, create the OpenProject database user and accompanied database.
```shell
$ 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.
Expand All @@ -89,7 +99,8 @@ $ createdb -O openproject openproject_test

## 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:
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 and node-build

Expand Down Expand Up @@ -132,7 +143,7 @@ node --version
v20.9.0

npm --version
10.1.0
10.5.0
```

# Install OpenProject
Expand All @@ -143,7 +154,8 @@ 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).
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
Expand Down Expand Up @@ -174,11 +186,14 @@ test:
database: openproject_test
```

To configure the environment variables such as the number of web server threads `OPENPROJECT_WEB_WORKERS`, copy the `.env.example` to `.env` and add the environment variables you want to configure. The variables will be automatically loaded to the application's environment.
To configure the environment variables such as the number of web server threads `OPENPROJECT_WEB_WORKERS`, copy
the `.env.example` to `.env` and add the environment variables you want to configure. The variables will be
automatically loaded to the application's environment.

## Finish the Installation of OpenProject

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)
- node_modules
- link plugin frontend modules
Expand All @@ -193,29 +208,38 @@ Now, run the following tasks to migrate and seed the dev database, and prepare t
```shell
RAILS_ENV=development bin/rails db:seed
```

1

## Run OpenProject through overmind

You can run all required workers of OpenProject through `overmind`, which combines them in a single tab. Optionally, you may also
You can run all required workers of OpenProject through `overmind`, which combines them in a single tab. Optionally, you
may also
run `overmind` as a daemon and connect to services individually.
The `bin/dev` command will first check if `overmind` is available and run the application if via `Procfile.dev` if possible. If not,
The `bin/dev` command will first check if `overmind` is available and run the application if via `Procfile.dev` if
possible. If not,
it falls back to `foreman`, installing it if needed.

```shell
bin/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](https://github.com/DarthSim/overmind/tree/v2.4.0#overmind-environment) as required.
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](https://github.com/DarthSim/overmind/tree/v2.4.0#overmind-environment) 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 and it has known issues with regards to memory (see background worker section below). To disable the worker process:
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 and it has known issues with regards to memory (see background worker section below). To
disable the worker process:

```shell
echo "OVERMIND_IGNORED_PROCESSES=worker" >> .overmind.env
```

For more information refer to the great Overmind documentation [usage section](https://github.com/DarthSim/overmind/tree/v2.4.0#usage).
For more information refer to the great Overmind
documentation [usage section](https://github.com/DarthSim/overmind/tree/v2.4.0#usage).

You can access the application with the admin-account having the following credentials:

Expand All @@ -242,10 +266,12 @@ To run the frontend server, please run
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,
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.
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.

### Delayed Job background worker

Expand Down Expand Up @@ -286,7 +312,8 @@ brew install subversion

### Git

To test the integration with Git repositories, we rely on the `git` command to be available. Git is either installed via the Xcode Command Line Tools, with [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or via homebrew.
To test the integration with Git repositories, we rely on the `git` command to be available. Git is either installed via
the Xcode Command Line Tools, with [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or via homebrew.

```shell
xcode-select --install
Expand All @@ -300,17 +327,22 @@ brew install git

### Spawning a lot of browser tabs

If you haven't run this command for a while, chances are that a lot of background jobs have queued up and might cause a significant amount of open tabs (due to the way we deliver mails with the letter_opener gem). To get rid of the jobs before starting the worker, use the following command. **This will remove all currently scheduled jobs, never use this in a production setting.**
If you haven't run this command for a while, chances are that a lot of background jobs have queued up and might cause a
significant amount of open tabs (due to the way we deliver mails with the letter_opener gem). To get rid of the jobs
before starting the worker, use the following command. **This will remove all currently scheduled jobs, never use this
in a production setting.**

```shell
RAILS_ENV=development bin/rails runner "Delayed::Job.delete_all"
```


## Start Coding

Please have a look at [our development guidelines](../code-review-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](https://github.com/opf/openproject/blob/dev/docs/development/running-tests) documentation (we like to have automated tests for every new developed feature).
Please have a look at [our development guidelines](../code-review-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](https://github.com/opf/openproject/blob/dev/docs/development/running-tests) documentation (we
like to have automated tests for every new developed feature).

## Troubleshooting

Expand All @@ -320,5 +352,7 @@ If an error occurs, it should be logged there (as well as in the output to STDOU

## 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.
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.
Loading