From c9934d84a10ab5662545afb5bb5831970dd7bf57 Mon Sep 17 00:00:00 2001 From: Aaron Contreras Date: Mon, 25 Mar 2024 12:16:14 -0500 Subject: [PATCH 1/2] Update node and npm versions expected * Bumps node version to 20.9.0 on Ubuntu instructions. * Bumps npm version to 10.5.0 on OSX and Ubuntu instructions. --- .../development-environment-osx/README.md | 88 ++++++++++----- .../development-environment-ubuntu/README.md | 106 ++++++++++++------ 2 files changed, 131 insertions(+), 63 deletions(-) diff --git a/docs/development/development-environment-osx/README.md b/docs/development/development-environment-osx/README.md index 8a6e2a77c9bd..ea57e1fd59fd 100644 --- a/docs/development/development-environment-osx/README.md +++ b/docs/development/development-environment-osx/README.md @@ -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 @@ -38,10 +43,12 @@ $ 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 @@ -49,7 +56,8 @@ and install that version. 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 @@ -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 @@ -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. @@ -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 @@ -132,7 +143,7 @@ node --version v20.9.0 npm --version -10.1.0 +10.5.0 ``` # Install OpenProject @@ -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 @@ -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 @@ -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: @@ -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 @@ -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 @@ -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 @@ -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. diff --git a/docs/development/development-environment-ubuntu/README.md b/docs/development/development-environment-ubuntu/README.md index 52ed199ef6e6..76a89d3795ef 100644 --- a/docs/development/development-environment-ubuntu/README.md +++ b/docs/development/development-environment-ubuntu/README.md @@ -10,21 +10,26 @@ keywords: development setup debian ubuntu linux To develop OpenProject a setup similar to that for using OpenProject in production is needed. This guide assumes that you have a Ubuntu 20.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._ +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 Development Environment will be installed with a PostgreSQL database, OpenProject on-premises installation shall NOT be present before. +OpenProject Development Environment will be installed with a PostgreSQL database, OpenProject on-premises installation +shall NOT be present before. **Please note**: This guide is NOT suitable for a production setup, but only for developing with it! Remark: *At the time of writing* in this page refers to 12/10/2021 -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 need an active Ruby and Node JS environment to run OpenProject. To this end, we need some packages installed on the system.o +We need an active Ruby and Node JS environment to run OpenProject. To this end, we need some packages installed on the +system.o -CPU recommendation: 4 CPUs, Memory recommendation: 8 better 16 GB (in general we need double the amount of a normal production installation) +CPU recommendation: 4 CPUs, Memory recommendation: 8 better 16 GB (in general we need double the amount of a normal +production installation) ```shell sudo apt-get update @@ -33,7 +38,10 @@ sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-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 "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 @@ -69,7 +77,8 @@ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build With both installed, we can now install ruby. 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 @@ -77,16 +86,19 @@ and install that version. 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 rbenv rehash ``` -You also need to install [bundler](https://github.com/bundler/bundler/), the ruby gem bundler (remark: if you run into an error, first try with a fresh reboot). +You also need to install [bundler](https://github.com/bundler/bundler/), the ruby gem bundler (remark: if you run into +an error, first try with a fresh reboot). -If you get `Command 'gem' not found...` here, ensure you followed the instructions `rbenv init` command to ensure it is loaded in your shell. +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 @@ -102,6 +114,7 @@ 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 `openproject-dev-password`. Now, create the database `openproject_dev` and `openproject_test` owned by the previously created user. @@ -116,7 +129,8 @@ Now, create the database `openproject_dev` and `openproject_test` owned by the p ## 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 @@ -149,8 +163,8 @@ You can find the latest LTS version here: [nodejs.org/en/download/](https://node At the time of writing this is v16.13.1 Install and activate it with: ```shell -nodenv install 16.13.1 -nodenv global 16.13.1 +nodenv install 20.9.0 +nodenv global 20.9.0 nodenv rehash ``` @@ -172,18 +186,20 @@ bundler --version Bundler version 2.5.5 node --version -v16.13.1 +v20.9.0 npm --version -8.3.0 +10.5.0 ``` # Install OpenProject Sources -In order to create a pull request to the core OpenProject repository, you will want to fork it to your own GitHub account. +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 [github.com/opf/openproject](https://github.com/opf/openproject) and press "Fork" on the upper right corner. +To do that, go to [github.com/opf/openproject](https://github.com/opf/openproject) and press "Fork" on the upper right +corner. ```shell # Download the repository @@ -194,7 +210,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 @@ -225,11 +242,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 @@ -247,26 +267,33 @@ RAILS_ENV=development bin/rails db:seed ## 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: @@ -293,10 +320,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. ### Background job worker @@ -306,23 +335,26 @@ RAILS_ENV=development bundle exec good_job start This will start a Delayed::Job worker to perform asynchronous jobs like sending emails. - - ## Known issues ### 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/tree/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/tree/dev/docs/development/running-tests) documentation (we +like to have automated tests for every new developed feature). ## Troubleshooting @@ -332,5 +364,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. From 2b45ecce9237d340bb18a8fff67c37567b5ea9be Mon Sep 17 00:00:00 2001 From: Dombi Attila <83396+dombesz@users.noreply.github.com> Date: Tue, 26 Mar 2024 09:13:47 +0200 Subject: [PATCH 2/2] Fix typo in description. --- docs/development/development-environment-ubuntu/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/development-environment-ubuntu/README.md b/docs/development/development-environment-ubuntu/README.md index 76a89d3795ef..67a208dc29bd 100644 --- a/docs/development/development-environment-ubuntu/README.md +++ b/docs/development/development-environment-ubuntu/README.md @@ -160,7 +160,7 @@ git clone https://github.com/nodenv/node-build.git $(nodenv root)/plugins/node-b You can find the latest LTS version here: [nodejs.org/en/download/](https://nodejs.org/en/download/) -At the time of writing this is v16.13.1 Install and activate it with: +At the time of writing this is v20.9.0 Install and activate it with: ```shell nodenv install 20.9.0