diff --git a/help/.DS_Store b/help/.DS_Store index 7e7fa89e58..397c73d7ca 100644 Binary files a/help/.DS_Store and b/help/.DS_Store differ diff --git a/help/development/README.md b/help/development/README.md index f7adfa711a..0666b3c58e 100644 --- a/help/development/README.md +++ b/help/development/README.md @@ -112,7 +112,6 @@ This code of conduct is adapted from the [Contributor Covenant](http://contribut # Additional resources -* [Quick Start for Developers](quick-start) * [Development environment for Ubuntu 16.04.](development-environment-ubuntu.md) * [Development environment for Mac OS X](development-environment-osx.md) diff --git a/help/development/development-environment-osx.md b/help/development/development-environment-osx.md index bf1b77bfac..e9b868c6a4 100644 --- a/help/development/development-environment-osx.md +++ b/help/development/development-environment-osx.md @@ -3,7 +3,7 @@ To develop OpenProject a setup similar to that for using OpenProject in production is needed. This guide assumes that you have a Mac OS Xinstallation installation with administrative rights. -OpenProject will be installed with a PostgreSQL database. This guide will work analogous with a MySQL installation, though. +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! @@ -13,9 +13,10 @@ If you find any bugs or you have any recommendations for improving this tutorial 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 2.6. +## 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.6" -Use [rbenv](https://github.com/rbenv/rbenv) and [ruby-build](https://github.com/rbenv/ruby-build#readme) to install Ruby 2.6.1. **Install rbenv and ruby-build** rbenv is a ruby version manager that lets you quickly switch between ruby versions. @@ -38,19 +39,19 @@ and install that version. ```bash # Install the required version as read from the Gemfile -[dev@ubuntu]# rbenv install 2.6.1 +rbenv install 2.6.5 ``` 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 -[dev@ubuntu]# rbenv global 2.6.1 +rbenv global 2.6.5 ``` You also need to install [bundler](https://github.com/bundler/bundler/), the ruby gem bundler. ```bash -[dev@ubuntu]# gem install bundler +gem install bundler ``` ## Setup PostgreSQL database @@ -95,11 +96,11 @@ $ nodenv init **Install latest LTS node version** You can find the latest LTS version here: https://nodejs.org/en/download/ -Currently, this is v10.15.3. Install and activate it with: +Currently, this is v12.13.0. Install and activate it with: ```bash -[dev@ubuntu]# nodenv install 10.15.3 -[dev@ubuntu]# nodenv global 10.15.3 +nodenv install 12.13.0 +nodenv global 12.13.0 ``` ## Verify your installation @@ -108,28 +109,28 @@ You should now have an active ruby and node installation. Verify that it works w ```bash $ ruby --version -ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-darwin16] +ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-darwin16] $ bundler --version -Bundler version 2.0.1 +Bundler version 2.0.2 $ npm --version -6.7.0 +12.13.0 ``` # Install OpenProject ```bash # Download the repository -[dev@ubuntu]# git clone https://github.com/opf/openproject.git -[dev@ubuntu]# cd openproject +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 -[dev@ubuntu]# bundle install +bundle install # Install node_modules -[dev@ubuntu]# npm install +npm install ``` 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). @@ -140,7 +141,7 @@ So, if you want to develop a feature, create a feature branch from a current `de Create and configure the database configuration file in `config/database.yml` (relative to the openproject-directory. ```bash -[dev@debian]# vim config/database.yml +vim config/database.yml ``` Now edit the `config/database.yml` file and insert your database credentials. @@ -163,15 +164,15 @@ test: database: openproject_test ``` -**NOTE:** If you want to use MySQL instead and have a database installed, simply use the MySQL section of the exemplary `database.yml.example` configuration file. + ## 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 -[dev@ubuntu]# export RAILS_ENV=development -[dev@ubuntu]# ./bin/rake db:migrate db:seed db:test:prepare +RAILS_ENV=development bin/rails db:create db:migrate +RAILS_ENV=development bin/rails db:seed db:test:prepare ``` @@ -181,8 +182,8 @@ You can run all required workers of OpenProject through `foreman`, which combine 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 -[dev@ubuntu]# gem install foreman -[dev@ubuntu]# foreman start -f Procfile.dev +gem install foreman +foreman start -f Procfile.dev ``` The application will be available at `http://127.0.0.1:5000`. To customize bind address and port copy the `.env.sample` provided in the root of this project as `.env` and [configure values][foreman-env] as required. @@ -206,19 +207,23 @@ To run OpenProject manually, you need to run the rails server and the webpack fr **Rails web server** ```bash -[dev@ubuntu]# RAILS_ENV=development ./bin/rails server +RAILS_ENV=development bin/rails server ``` This will start the development server on port `3000` by default. -**Webpack bundling** +**Angular frontend** + +To run the frontend server, please run ```bash -[dev@ubuntu]# RAILS_ENV=development npm run webpack-watch +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.js frontend part. +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 @@ -228,11 +233,7 @@ Also, take a look at the `doc` directory in our sources, especially the [how to ## Troubleshooting -The OpenProject logfile can be found here: - -``` -/home/openproject/openproject/log/development.log -``` +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). diff --git a/help/development/development-environment-ubuntu.md b/help/development/development-environment-ubuntu.md index 45e8afc6c9..adbd90489c 100644 --- a/help/development/development-environment-ubuntu.md +++ b/help/development/development-environment-ubuntu.md @@ -5,7 +5,7 @@ To develop OpenProject a setup similar to that for using OpenProject in producti 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. Support for MySQL was removed from `dev` branch before release of version 10. +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! @@ -16,31 +16,31 @@ If you find any bugs or you have any recommendations for improving this tutorial 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 -[dev@ubuntu]# sudo apt-get update -[dev@ubuntu]# sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-dev libmysqlclient-dev libpq-dev libreadline-dev libffi6 +sudo apt-get update +sudo apt-get install git curl build-essential zlib1g-dev libyaml-dev libssl-dev libpq-dev libreadline-dev libffi6 ``` -## Install Ruby 2.6. +## Install Ruby -Use [rbenv](https://github.com/rbenv/rbenv) and [ruby-build](https://github.com/rbenv/ruby-build#readme) to install Ruby 2.6. +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.6" - -**Install rbenv** +**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 -[dev@ubuntu]# git clone https://github.com/rbenv/rbenv.git ~/.rbenv +git clone https://github.com/rbenv/rbenv.git ~/.rbenv # Optional: Compile bash extensions -[dev@ubuntu]# cd ~/.rbenv && src/configure && make -C src +cd ~/.rbenv && src/configure && make -C src # Add rbenv to the shell's $PATH. -[dev@ubuntu]# echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc +echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc # Run rbenv-init and follow the instructions to initialize rbenv on any shell -[dev@ubuntu]# ~/.rbenv/bin/rbenv init +~/.rbenv/bin/rbenv init # Source bashrc -[dev@ubuntu]# source ~/.bashrc +source ~/.bashrc ``` **Installing ruby-build** @@ -48,7 +48,7 @@ rbenv is a ruby version manager that lets you quickly switch between ruby versio ruby-build is an addon to rbenv that installs ruby versions ```bash -[dev@ubuntu]# git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build +git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build ``` **Installing ruby-2.6** @@ -61,35 +61,36 @@ and install that version. ```bash # Install the required version as read from the Gemfile -[dev@ubuntu]# rbenv install 2.6.3 +rbenv install 2.6.5 ``` 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 -[dev@ubuntu]# rbenv global 2.6.3 +rbenv global 2.6.5 +rbenv rehash ``` You also need to install [bundler](https://github.com/bundler/bundler/), the ruby gem bundler. ```bash -[dev@ubuntu]# gem install 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. + ## Setup PostgreSQL database Next, install a PostgreSQL database. -(Looks counter-intuitive but for the time being we also need the `mysql-client`. It is required for migration from MySQL to PostgreSQL code.) - ```bash -[dev@debian]# sudo apt-get install postgresql postgresql-client mysql-client +[dev@debian]# sudo apt-get install postgresql postgresql-client ``` Create the OpenProject database user and accompanied database. ```bash -[dev@ubuntu]# sudo su postgres +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`. @@ -112,32 +113,33 @@ We will install the latest LTS version of Node.js via [nodenv](https://github.co ```bash # Install nodenv -[dev@ubuntu]# git clone https://github.com/nodenv/nodenv.git ~/.nodenv +git clone https://github.com/nodenv/nodenv.git ~/.nodenv # Optional: Install bash extensions -[dev@ubuntu]# cd ~/.nodenv && src/configure && make -C src +cd ~/.nodenv && src/configure && make -C src # Add nodenv to the shell's $PATH. -[dev@ubuntu]# echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.bashrc +echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.bashrc # Run nodenv init and follow the instructions to initialize nodenv on any shell -[dev@ubuntu]# ~/.nodenv/bin/nodenv init +~/.nodenv/bin/nodenv init # Source bashrc -[dev@ubuntu]# source ~/.bashrc +source ~/.bashrc ``` **Install node-build** ```bash -[dev@ubuntu]# git clone https://github.com/nodenv/node-build.git $(nodenv root)/plugins/node-build +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/ -Currently, this is v10.15.3 Install and activate it with: +Currently, this is v12.13.0 Install and activate it with: ```bash -[dev@ubuntu]# nodenv install 10.15.3 -[dev@ubuntu]# nodenv global 10.15.3 +nodenv install 12.13.0 +nodenv global 12.13.0 +nodenv rehash ``` ## Verify your installation @@ -145,29 +147,29 @@ Currently, this is v10.15.3 Install and activate it with: You should now have an active ruby and node installation. Verify that it works with these commands. ```bash -[dev@ubuntu]# ruby --version -ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux] +ruby --version +ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-linux] -[dev@ubuntu]# bundler --version -Bundler version 2.0.1 +bundler --version +Bundler version 2.0.2 -[dev@ubuntu]# npm --version -6.7.0 +npm --version +6.12.0 ``` # Install OpenProject ```bash # Download the repository -[dev@ubuntu]# git clone https://github.com/opf/openproject.git -[dev@ubuntu]# cd openproject +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 -[dev@ubuntu]# bundle install +bundle install # Install node_modules -[dev@ubuntu]# npm install +npm install ``` 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). @@ -206,8 +208,8 @@ test: Now, run the following tasks to migrate and seed the dev database, and prepare the test setup for running tests locally. ```bash -[dev@ubuntu]# export RAILS_ENV=development -[dev@ubuntu]# ./bin/rake db:migrate db:seed db:test:prepare +RAILS_ENV=development bin/rails db:migrate +RAILS_ENV=development bin/rails db:seed ``` @@ -217,8 +219,8 @@ You can run all required workers of OpenProject through `foreman`, which combine 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 -[dev@ubuntu]# gem install foreman -[dev@ubuntu]# foreman start -f Procfile.dev +gem install foreman +foreman start -f Procfile.dev ``` The application will be available at `http://127.0.0.1:5000`. To customize bind address and port copy the `.env.sample` provided in the root of this project as `.env` and [configure values][foreman-env] as required. @@ -242,7 +244,7 @@ To run OpenProject manually, you need to run the rails server and the webpack fr **Rails web server** ```bash -[dev@ubuntu]# RAILS_ENV=development ./bin/rails server +RAILS_ENV=development ./bin/rails server ``` This will start the development server on port `3000` by default. @@ -252,7 +254,7 @@ This will start the development server on port `3000` by default. To run the frontend server, please run ```bash -[dev@ubuntu]# RAILS_ENV=development npm run serve +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, diff --git a/help/development/quick-start.md b/help/development/quick-start.md deleted file mode 100644 index 680c939d47..0000000000 --- a/help/development/quick-start.md +++ /dev/null @@ -1,47 +0,0 @@ -# Quick start for developers - - -Detailed installation instructions for different platforms are located on the [OpenProject website](https://www.openproject.org/download/). - -You can find information on configuring OpenProject in [`config/CONFIGURATION.md`](CONFIGURATION.md). - -## Fast install (Docker version) - -### Prerequisites - -* Git -* [Docker Engine](https://docs.docker.com/engine/installation/) -* [Docker Compose](https://docs.docker.com/compose/) - -### Building and running - -1. Build the image (this will take some time) - - docker-compose build - -2. Start and setup the database - - docker-compose up -d db - cp config/database.docker.yml config/database.yml - docker-compose run web rake db:create db:migrate db:seed - -3. Start the other processes - - docker-compose up - -Assets should be automatically recompiled anytime you make a change, and your -ruby code should also be reloaded when you change a file locally. - -You can run arbitrary commands in the context of the application by using -`docker-compose run`. For instance: - - docker-compose run web rake db:migrate - docker-compose run web rails c - ... - -## Manual development environment - -Please see the following guides for detailed instructions on how to get started developing for OpenProject. - -- [Development environment for Ubuntu 16.04.](./development-environment-ubuntu.md) -- [Development environment for Mac OS X](./development-environment-osx.md) diff --git a/help/installation-and-operations/README.md b/help/installation-and-operations/README.md index b67716aa58..d7a45736e2 100644 --- a/help/installation-and-operations/README.md +++ b/help/installation-and-operations/README.md @@ -7,11 +7,11 @@ This section concerns the installation and operation of OpenProject (Community a | Main Topics | Description | | ----------- | :---------- | | [System requirements](system-requirements) | Learn the minimum configuration required to run OpenProject | -| [Installation with DEB/RPM packages](packaged/installation) | How to install OpenProject from DEB/RPM packages | -| [Installation with Docker](docker/installation) | How to install OpenProject with Docker | +| [Installation with DEB/RPM packages](packaged/) | How to install OpenProject from DEB/RPM packages | +| [Installation with Docker](docker/) | How to install OpenProject with Docker | | [Operation & Maintenance](operation/) | Guides on how to configure, backup, upgrade, and monitor your OpenProject installation | | [Advanced configuration](advanced-configuration/) | Guides on how to perform advanced configuration of your OpenProject installation | -For production environments and when using a [supported distribution](system-requirements), we recommend using the [packaged installation](packaged/installation). This will install OpenProject as a system dependency using your distribution's package manager, and provide updates in the same fashion that all other system packages do. +For production environments and when using a [supported distribution](system-requirements), we recommend using the [packaged installation](packaged/). This will install OpenProject as a system dependency using your distribution's package manager, and provide updates in the same fashion that all other system packages do. A [manual installation](manual/installation) option is also documented, but due to the large number of components involved and the rapid evolution of OpenProject, we cannot ensure that the procedure is either up-to-date or that it will correctly work on your machine. This mean if installation is NOT recommended. diff --git a/help/installation-and-operations/configuration/README.md b/help/installation-and-operations/configuration/README.md new file mode 100644 index 0000000000..581ad8369c --- /dev/null +++ b/help/installation-and-operations/configuration/README.md @@ -0,0 +1,9 @@ +--- +sidebar_navigation: + title: Advanced configuration + priority: 100 +--- + +# Advanced configuration + +TODO diff --git a/help/installation-and-operations/docker/README.md b/help/installation-and-operations/docker/README.md index 5714c4003a..488f960323 100644 --- a/help/installation-and-operations/docker/README.md +++ b/help/installation-and-operations/docker/README.md @@ -1,10 +1,9 @@ --- sidebar_navigation: title: Docker installation - priority: 200 + priority: 300 --- # Docker installation TODO - diff --git a/help/installation-and-operations/manual/backup.md b/help/installation-and-operations/manual/backup.md deleted file mode 100644 index 1bcc9e7ef1..0000000000 --- a/help/installation-and-operations/manual/backup.md +++ /dev/null @@ -1,116 +0,0 @@ -# Backup Guide - -We advice to backup your OpenProject installation regularly — especially before upgrading to a newer version. - -## Backup the Database - -###OpenProject Version 3.0.15 and newer - -Execute the following command in a shell in the directory where OpenProject is installed: - -```bash -RAILS_ENV=production bundle exec rake backup:database:create -``` - -The command will create dump of your database which can be found at `OPENPROJECT_DIRECTORY/backup/openproject-production-db-.sql` (for MySQL) or `OPENPROJECT_DIRECTORY/backup/openproject-production-db-.backup` (for PostgreSQL). - -Optionally, you can specify the path of the backup file. Therefore you have to replace the `/path/to/file.backup` with the path of your choice - -```bash -RAILS_ENV=production bundle exec rake backup:database:create[/path/to/backup/file.backup] -``` -*Note:* You can restore any database backup with the following command. Be aware that you have to replace the `/path/to/backup/file.backup` path with your actual backup path. - -```bash -RAILS_ENV=production bundle exec rake backup:database:restore[/path/to/backup/file.backup] -``` - -If your database dump is from an old version of OpenProject, also run the following command after the restore: - -```bash -RAILS_ENV=production bundle exec rake db:migrate -``` - -to migrate your data to the database structure of your installed OpenProject version. - -### OpenProject prior Version 3.0.15 - -Determine which Database you are using. You can find the relevant information in the `OPENPROJECT_DIRECTORY/config/database.yml` file. It looks similar to this: - -```yaml -production: - adapter: postgresql - database: openproject-production - host: localhost - username: my_postgres_user - password: my_secret_password - encoding: utf8 - min_messages: warning -``` - -Locate the database entry for your production database. If your adapter is postgresql, then you have a PostgreSQL database. If it is mysql2, you use a MySQL database. Now follow the steps for your database adapter. - -#### PostgreSQL -You can backup your PostgreSQL database with the `pg_dump` command and restore backups with the `pg_restore` command. (There might be other (and more convenient) tools, like pgAdmin, depending on your specific setup.) - -An example backup command with `pg_dump` looks like this: - -```bash -pg_dump --clean --format=custom --no-owner --file=/path/to/your/backup/file.backup --username=POSTGRESQL_USER --host=HOST DATABASE_NAME -``` - -Please, replace the path to your backup file, the username, host, and database name with your actual data. You can find all relevant information in the database.yml file. - -Consult the man page of `pg_dump` for more advanced parameters, if necessary. - -The database dump can be restored similarly with `pg_restore`: - -```bash -pg_restore --clean --no-owner --single-transaction ---dbname=DATABASE_NAME --host=HOST --username=POSTGRESQL_USER -/path/to/your/backup/file.backup -``` - -Consult the man page of `pg_restore` for more advanced parameters, if necessary. - -#### MySQL -You can backup your MySQL database for example with the mysqldump command and restore backups with the mysql command line client. (There might be other (and more convenient) tools, like phpMyAdmin, adminer, or other tools, depending on your specific setup.) - -An example backup command with `mysqldump` looks like this: - -```bash -mysqldump --single-transaction --add-drop-table --add-locks --result-file=/path/to/your/backup/file.sql --host=HOST --user=MYSQL_USER --password DATABASE_NAME -``` - -Please, replace the path to your backup file, the MySQL username, host and database name with your actual data. You can find all relevant information in the `database.yml` file. - -Consult the man page of `mysqldump` for more advanced parameters, if necessary. - -The database dump can be restored similarly with `mysql` (on a \*nix compatible shell): - -```bash -mysql --host=HOST --user=MYSQL_USER --password DATABASE_NAME < /path/to/your/backup/file.sql -``` -Consult the man page of mysql for more advanced parameters, if necessary. - -## Backup your Configuration Files -Please make sure to create a backup copy of at least the following configuration files (all listed as a relative path from the OpenProject installation directory): - -`Gemfile.local` (if present) -`Gemfile.plugins` (if present) -`config/database.yml` (if present) -`config/configuration.yml` (if present) -`config/settings.yml` (if present) - -Some OpenProject options can be given as environment variables. If you have configured environment variables for OpenProject, consider to backup them too. - -## Backup Files Uploaded by Users (attachments) -Files uploaded by users (e.g. when adding an attachment to a WorkPackage) are stored on the hard disk. The directory where those files are stored can be configured in the `config/configuration.yml` via the `attachments_storage_path` setting (or an -appropriate environment variable). - -If you have not changed the `attachment_storage_path` setting, all files will be uploaded to the files directory (relative to your OpenProject installation). - -Make sure to backup this directory. - -## Backup Repositories -You can manage Repositories with OpenProject — so one or more of your projects may have a repository. Please make sure to backup these too. The path to a project’s repository can be found in the repository settings of the respective project (it can be individually defined for every project). Each of the defined locations has to be backed up. diff --git a/help/installation-and-operations/manual/README.md b/help/installation-and-operations/manual/installation.md similarity index 99% rename from help/installation-and-operations/manual/README.md rename to help/installation-and-operations/manual/installation.md index c40d2ae4d4..b602dacf25 100644 --- a/help/installation-and-operations/manual/README.md +++ b/help/installation-and-operations/manual/installation.md @@ -2,7 +2,7 @@ sidebar_navigation: false --- -# Manual installation of OpenProject with Apache on Ubuntu 18.04 LTS +# Manual installation guide **IMPORTANT: We strongly recommend to use one of the officially supported [installation methods](../installation). This guide is simply provided as a reference, and is most likely NOT up to date wit relation to the latest OpenProject releases.** diff --git a/help/installation-and-operations/manual/postgresql-migration.md b/help/installation-and-operations/manual/postgresql-migration.md deleted file mode 100644 index f83ea013ed..0000000000 --- a/help/installation-and-operations/manual/postgresql-migration.md +++ /dev/null @@ -1,188 +0,0 @@ -# Migrating your manual-installation OpenProject database to PostgreSQL - -This guide will migrate your MySQL installation on a manual installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). - -## Backing up - -Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore documentation](https://www.openproject.org/operations/backup/backup-guide-manual-installation/) for Docker-based installations. - - - -## Set up a PostgreSQL database - -Please first set up a PostgreSQL database. These are generic apt-based installation steps, please adapt them appropriately for your distribution. - -OpenProject requires at least PostgreSQL 9.5 installed. Please check if your distributed package is too old. - -```bash -[root@host] apt-get install postgresql postgresql-contrib libpq-dev -``` - -Once installed, switch to the PostgreSQL system user. - -```bash -[root@host] su - postgres -``` - -Then, as the PostgreSQL user, create the system user for OpenProject. This will prompt you for a password. We are going to assume in the following guide that password were 'openproject'. Of course, please choose a strong password and replace the values in the following guide with it! - -```bash -[postgres@host] createuser -W openproject -``` - -Next, create the database owned by the new user - -```bash -[postgres@host] createdb -O openproject openproject -``` - -Lastly, exit the system user - -```bash -[postgres@host] exit -# You will be root again now. -``` - - - -## The MYSQL_DATABASE_URL - -Note down or copy the current MySQL `DATABASE_URL`. The following command exports it to the curent shell as `MYSQL_DATABASE_URL`: - -```bash -# Will look something something of the kind -# mysql2://user:password@localhost:3306/dbname - -# Pass into the container but replace mysql2 with mysql! -export MYSQL_DATABASE_URL="mysql://user:password@localhost:3306/dbname" -``` - - - -**Please note:** Ensure that the URL starts with `mysql://` , not with ` mysql2://` ! - - - -## The PostgreSQL DATABASE_URL - -Pass in `DATABASE_URL` pointing to your new PostgreSQL database. Fill the template below with the password you entered above. - -```bash -export POSTGRES_DATABASE_URL="postgresql://openproject:@localhost/openproject" -``` - -## Running the migration via Docker - -OpenProject provides a simple conversion script that you can run as a single command via Docker. - -To run the migration script within the container, simply run the following command, replacing the content of the environment variables with your actual values. - - -### Adapting the hostname - -**Note:** Depending on your docker installation and networking, you may need to replace the hostname `localhost` in the database URLs -with `host.docker.internal` to access the docker host. On Mac for example, localhost will refer to the docker client. - - -```bash -docker run -it \ - -e MYSQL_DATABASE_URL=$MYSQL_DATABASE_URL \ - -e DATABASE_URL=$POSTGRES_DATABASE_URL \ - openproject/community:latest -``` - - -This will perform all necessary steps to perform the migration. Afterwards, simply remove the `MYSQL_DATABASE_URL`environment variable again and start your container as usual. - - - -## Running the migration without Docker - -### Installation of pgloader - - - -#### Apt Systems - -For systems with APT package managers (Debian, Ubuntu), you should already have `pgloader` available and can install as root with with: - -``` -[root@host] apt-get install pgloader -``` - - - -[For other installations, please see the project page itself for steps on installing with Docker or from source](https://github.com/dimitri/pgloader#install). - - - -After installation, check that pgloader is in your path and accessible: - - - -``` -[root@host] pgloader --version - -# Should output something of the kind -pgloader version "3.5.2" -compiled with SBCL 1.4.5.debian -``` - - - -### Performing the migration - -You are now ready to use `pgloader`. You simply point it the old and new database URL while specifying the option -`--with "preserve index names"` which ensures that index names are kept identical. - -```bash -pgloader --verbose --with "preserve index names" $MYSQL_DATABASE_URL $POSTGRES_DATABASE_URL -``` - -This might take a while depending on current installation size. - -### Index attachments for fulltext search - -One of the benefits of using PostgreSQL over MySql is the support for fulltext search on attachments. The fulltext search feature relies on the existence of two additional columns for attachments that need to be added now ff the migration to PostgreSql is done for an OpenProject >= **8.0**. If the OpenProject version is below **8.0** the next two commands can be skipped. - -In order to add the necessary columns to the database, run - -```bash -openproject run rails db:migrate:redo VERSION=20180122135443 -``` - -After the columns have been added, the index has to be created for already uploaded attachments - -```bash -openproject run rails attachments:extract_fulltext_where_missing -``` - -If a large set of attachments already exists, executing the command might take a while. - - - -### Indexes on relations table - -You will also need to rebuild the index on the relations table. Simply run the following command -to re-run the migration. - -```bash -openproject run rails db:migrate:redo VERSION=20180105130053 -``` - - - -## Optional: Uninstall MySQL - -If you installed MySQL only for the installation of OpenProject, evaluate whether you want to remove MySQL server. - -You can check the output of `dpkg - l | grep mysql` to check for packages removable. Only keep `libmysqlclient-dev` for Ruby dependencies on the mysql adapter. - - - -The following is an exemplary removal of an installed version MySQL 5.7. - -``` -[root@host] apt-get remove mysql-server -``` - diff --git a/help/installation-and-operations/manual/upgrading.md b/help/installation-and-operations/manual/upgrading.md deleted file mode 100644 index 834ca6c761..0000000000 --- a/help/installation-and-operations/manual/upgrading.md +++ /dev/null @@ -1,334 +0,0 @@ -# OpenProject 8.x to OpenProject 9.x Debian/Ubuntu Upgrade Guide (Manual installation) - -OpenProject 9.x is being released at https://github.com/opf/openproject under the branch `stable/9`. -Follow the following steps to perform the upgrade: - -First, perform a backup for your current environment - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# RAILS_ENV="production" bundle exec rake backup:database:create -# Backup will be created under backup/ -``` - -Depending on from what version you're upgrading, you may need to add the correct remote -Then, check out the stable version of OpenProject 9.x. - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# git remote -v | grep openproject-ce -``` - -If this returns anything, update the remote to the correct URL. - -```bash -[openproject@debian]# git remote set-url origin https://github.com/opf/openproject.git -``` - -Then, refresh that origin and checkout the stable/9 branch. - -```bash -[openproject@debian]# git fetch && git checkout stable/9 -``` - -After upgrading the installation files, you need to migrate the installation to OpenProject 9.0 with the following steps: - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# rm -rf frontend/node_modules && npm install -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:seed -[openproject@debian]# RAILS_ENV="production" bundle exec rake assets:precompile -[openproject@debian]# touch tmp/restart.txt -``` - -After performing these steps, the server should be running OpenProject 9.0.x. - - -## Upgrade notes - -These following points are some known issues around the update to 9.0. -It does not contain the entire list of changes. - -To see all changes, [please browse the release notes](https://www.openproject.org/release-notes/openproject-9-0-0/). - -### MySQL is being deprecated - -OpenProject 9.0. is deprecating MySQL support. You can expect full MySQL support for the course of 9.0 releases, but we -are likely going to be dropping MySQL completely in one of the following releases. - -For more information regarding motivation behind this and migration steps, please see https://www.openproject.org/deprecating-mysql-support/ -In this post, you will find documentation for a mostly-automated migration script to PostgreSQL to help you get up and running with PostgreSQL. - -# OpenProject 7.x to OpenProject 8.x Debian/Ubuntu Upgrade Guide (Manual installation) - -OpenProject 8.x is being released at https://github.com/opf/openproject-ce using the branch `stable/8`. -Follow the following steps to perform the upgrade: - -These following points are some known issues around the update to 8.0. It does not contain the entire list of changes. To see all changes, [please browse the release notes](https://www.openproject.org/release-notes/openproject-8-0/). - -### Migration from Textile to Markdown - -OpenProject 8.0. has removed Textile, all previous content is migrated to GFM Markdown using [pandoc](https://pandoc.org). This will happen automatically during the migration run. A recent pandoc version will be downloaded by OpenProject. - -For more information, please visit this separate guide: https://github.com/opf/openproject/tree/dev/docs/user/textile-to-markdown-migration - -### Frontend changes, Angular is now in production - -OpenProject 8.0. uses Angular for the majority of the frontend application. The `npm install` step should automatically take care of the installation, however in some cases there were leftover `node_modules` entries that resulted in an incomplete frontend application. To ensure the correct versions are installed, we thus recommend you remove `frontend/node_modules` entirely before running `npm install` again. - -### SQL mode changes for MySQL 8.0. - -MySQL 8.0. removes the deprecated SQL mode `no_auto_create_user` that we enforced up until 7.4. You will need to remove this mode from your `config/database.yml` should you have used it. For more information, see https://community.openproject.com/wp/28524 - -# OpenProject 6.x to OpenProject 7.x Debian/Ubuntu Upgrade Guide (Manual installation) - -Please look at the steps in the section about the upgrade to OpenProject 6.0. OpenProject 7.x is being released under the branch `stable/7`. The other steps are identical. - -### Frontend changes, bower is no longer required - -With OpenProject 7.0., we no longer depend on `bower` for some on the frontend assets. Please ensure you remove `/frontend/bower_components` and `/frontend/bower.json`. - -### When running with MySQL: Required changes in sql_mode - -If you're upgrading to OpenProject 7.x with a MySQL installation, you will need to update your database.yml to reflect some necessary changes to MySQL `sql_mode` made as part of the migration to Rails 5. Please see the `config/database.yml.example` file for more information. - -# OpenProject 5.0.x to OpenProject 6.0 Debian/Ubuntu Upgrade Guide - -Upgrading your OpenProject 5.0.x installation to 6.0 is very easy. Please upgrade your OpenProject installation first to the latest stable 6.0 path. -If you checked out the OpenProject installation through Git, you can use the `stable/6` branch which points to the latest stable release. - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# git fetch && git checkout stable/6 -``` - -After upgrading the installation files, you need to migrate the installation to OpenProject 6.0 with the following steps: - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# npm install -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:seed -[openproject@debian]# RAILS_ENV="production" bundle exec rake assets:precompile -[openproject@debian]# touch tmp/restart.txt -``` - -After performing these steps, the server should be running OpenProject 6.0.x. - - -# OpenProject 4.2 to OpenProject 5.0 Debian/Ubuntu Upgrade Guide - -One of the main new features of OpenProject 5.0 is that it provides management of repositories directly within the user interface (with so-called *managed* repositories). - -Starting with OpenProject 5.0, you can explicitly select the SCM vendor you want to associate to your project, and let OpenProject generate the repository on the filesystem on the fly. - -If you haven't configured serving repositories through Apache before, you'll find the [repository integration guide](./repository-integration.md) to guide you through the necessary steps to configure this integration. - -For the other steps necessary to upgrade to OpenProject 5.0 please look -at the sections below and exchange `v4.1.0` with `v5.0.0`. - -## Changed Rails Path - -OpenProject 5.0 employs Rails 4.2.x, which contains a number of changes regarding paths. Foremost, files previously located in the `scripts` directory now reside in `bin` (e.g., `delayed_job`). - -### Secret Token - -With an update to Rails 4.1+, you now must generate a secret key base for the production environment with `./bin/rake secret` and make that available through the environment variable `SECRET_KEY_BASE`. - -You will likely set the environment variable in `/etc/environment` or use your server's environment mechanism (i.e., `SetEnv` in Apache). - -## Upgrading to Managed Repositories - -You can create repositories explicitly on the filesystem using managed repositories. -Enable managed repositories for each SCM vendor individually using the templates -defined in configuration.yml. For more information, please refer to the [repository integration guide](./repository-integration.md). - -This functionality was previously provided as a cron job `reposman.rb`. -This script has been integrated into OpenProject. -Please remove any existing cronjobs that still use this script. - -### Convert Repositories Created by Reposman - -If you want to convert existing repositories previously created (by reposman.rb or manually) -into managed repositories, use the following command: - - $ ./bin/rake scm:migrate:managed[URL prefix (, URL prefix, ...)] - -the URL prefix denotes a common prefix of repositories whose status should be upgraded to `:managed`. -Example: - -If you have executed reposman.rb with the following parameters: - - $ reposman.rb [...] --svn-dir "/opt/svn" --url "file:///opt/svn" - -Then you can pass the task a URL prefix `file:///opt/svn` and the rake task will migrate all repositories -matching this prefix to `:managed`. -You may pass more than one URL prefix to the task. - -### Listing Potential Conflicting Identifiers - -As managed repositories on the filesystem are uniquely associated using the project identifier, any existing directories in the managed repositories root *may* cause a conflict in the future when trying to create a repository with the same name. - -To help you identify these conflicts, you can run the following rake task, which will list entries in the managed repositories path with no associated project: - - $ ./bin/rake scm:find_unassociated - -# OpenProject 4.1 to OpenProject 4.2 Debian/Ubuntu Upgrade Guide - -Please look at the steps in the section about the upgrade to OpenProject 4.1. Just exchange `v4.1.0` to `v4.2.0` when checking out the git repository. - -# OpenProject 4.0 to OpenProject 4.1 Debian/Ubuntu Upgrade Guide - -This guide describes the upgrade process from OpenProject 4.0 to 4.1 on Debian 7.7 and Ubuntu 14.04 LTS step by step. - -Note: We strongly recommend to update your OpenProject installation to the latest available 4.0 version (currently 4.0.9), before attempting an update to 4.1. - - -## Preparation - -* Backup your current Openproject installation. Typically you should backup the attachment - folder of your installation, the subversion repositories (if applicable) and your database. - For more information please have a look at our [backup guide](backup-guide.md) - -* Before Upgrading, check that all the installed OpenProject plugins support the new - OpenProject version. Remove incompatible plugins before attempting an upgrade. Stop - the OpenProject Server. You may even add a maintenance page, if you feel comfortable - with that. - -* If you run the worker process with a cronjob, disable the cronjob temporarily. -* Stop the (delayed\_job) worker process. In case you run the worker process through - `RAILS_ENV=production bundle exec script/delayed_job start`, execute the following: - `RAILS_ENV=production bundle exec script/delayed_job stop`. - -## Update your system - -```bash -[root@debian]# apt-get update -[root@debian]# apt-get upgrade -``` - -## Get the new OpenProject Source Code -Change into the directory where OpenProject is installed and switch to the operating-system-user the OpenProject operates as. We assume that OpenProject is installed in `/home/openproject/openproject` by the `openproject` user. - -```bash -[root@debian]# su - openproject -c "bash -l" -[openproject@debian]# cd ~/openproject/openproject -``` - -Remove manual changes and modifications (If you have modified OpenProject source files and want to preserve those changes, back up your changes, and re-apply them later): - -```bash -[openproject@debian]# git reset --hard -[openproject@debian]# git fetch -[openproject@debian]# git checkout v4.1.0 -``` - -## Upgrade Ruby -OpenProject 4.1 requires Ruby to be installed in version 2.1.x. Assuming you have installed Ruby via RVM, do the following to upgrade your Ruby installation: - -```bash -[openproject@debian]# rvm get stable -[openproject@debian]# export -f rvm_debug -[openproject@debian]# rvm install 2.1.5 -[openproject@debian]# rvm use --default 2.1.5 -[openproject@debian]# gem install bundler -[openproject@debian]# bundle install -``` - -### Update application server configuration -This sections only applies to you, if you serve OpenProject via Apache and Passenger. If you serve OpenProject in a different way, be sure to check that it still works. - -During the upgrade of the Ruby version, we have potentially installed a new Ruby and Passenger version. The versions of Ruby and Passenger appear in the Apache configuration like this: - -```apache -LoadModule passenger_module /home/openproject/.rvm/gems/ruby-2.1.4/gems/passenger-4.0.53/buildout/apache2/mod_passenger.so - - PassengerRoot /home/openproject/.rvm/gems/ruby-2.1.4/gems/passenger-4.0.53 - PassengerDefaultRuby /home/openproject/.rvm/gems/ruby-2.1.4/wrappers/ruby - -``` -Please run the following commands to upgrade passenger and re-install the Apache module: - -```bash -[openproject@debian]# gem update passenger -[openproject@debian]# gem cleanup passenger -[openproject@debian]# passenger-install-apache2-module -``` - -The output of passenger-install-apache2-module2 tells you how to configure Apache. It is basically the same as what is already installed, except for the updated version numbers. - -Don’t forget to restart apache after the configuration change: - -```bash -[root@debian]# service apache2 reload -``` - -## Node.js installation -Node.js is necessary to precompile the assets (JavaScript and CSS). We will install the latest 0.12.x version of Node.js via nodeenv: - -```bash -[openproject@debian]# exit -[root@debian]# apt-get install python python-pip -[root@debian]# pip install nodeenv -[root@debian]# su - openproject -c "bash -l" -[openproject@debian]# cd /home/openproject -[openproject@debian]# nodeenv nodeenv -[openproject@debian]# source ./nodeenv/bin/activate -``` - -As a reference, the following Node.js and NPM versions have been installed on our system: - -```bash -[openproject@debian]# node --version - v0.12.2 -[openproject@debian]# npm --version - 1.4.28 -``` - -## The Upgrade - -Now that the sources and dependencies are in place, you can migrate the Database and do the upgrade. - -Before actually migrating the database, please remove all temporary files from the previous installation (caches, sessions) by running the following command. - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# RAILS_ENV="production" bundle exec rake tmp:clear -``` - -If you do not clear the temporary files, you may encounter an error of the form `NoMethodError: undefined method `map' for #` in the `config/initializers/30-patches.rb` files. -The actual upgrade commands are as follows: - -```bash -[openproject@debian]# cd /home/openproject/openproject -[openproject@debian]# npm install -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate -[openproject@debian]# RAILS_ENV="production" bundle exec rake db:seed -[openproject@debian]# RAILS_ENV="production" bundle exec rake assets:precompile -[openproject@debian]# touch tmp/restart.txt -``` - -To make sure that all work package attachments are indexed, so that their content can be used in work package filters -run: - -```bash -[openproject@debian]# RAILS_ENV="production" rake attachments:extract_fulltext_where_missing -``` - - - -*Side note:* If you are using `RAILS_ENV="development"` the task `bundle exec rake assets:webpack` needs to be run. This step is not necessary for `production` because it is part of the `asset:precompile` tasks. - -**NOTE** `db:seed` can also be invoked with a 'LOCALE' environment variable defined, specifying the language in which to seed. Note however, that specifying different locales for calls to `db:seed` might lead to a mixture of languages in your data. It is therefore advisable to use the same language for all calls to `db:seed`. - -## The Aftermath -* Re-enable the `delayed_job` cron job that was disabled in the first step. -* If you have put up a maintenance page, remove it. -* Start the OpenProject server again -* Watch for further OpenProject updates in our news, or on twitter. - -## 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 forum. - -Also, please take a look at the Frequently [Asked Questions](https://www.openproject.org/help/faq/). diff --git a/help/installation-and-operations/misc/README.md b/help/installation-and-operations/misc/README.md new file mode 100644 index 0000000000..f2d1eaa196 --- /dev/null +++ b/help/installation-and-operations/misc/README.md @@ -0,0 +1,9 @@ +--- +sidebar_navigation: + title: Other + priority: 0 +--- + +# Guides for infrequent operations + +TODO diff --git a/help/installation-and-operations/operation/README.md b/help/installation-and-operations/operation/README.md new file mode 100644 index 0000000000..57f3fe3c90 --- /dev/null +++ b/help/installation-and-operations/operation/README.md @@ -0,0 +1,9 @@ +--- +sidebar_navigation: + title: Operation + priority: 200 +--- + +# Operating OpenProject + +TODO diff --git a/help/installation-and-operations/operation/backing-up.md b/help/installation-and-operations/operation/backing-up.md new file mode 100644 index 0000000000..e204f34bb6 --- /dev/null +++ b/help/installation-and-operations/operation/backing-up.md @@ -0,0 +1,48 @@ +--- +sidebar_navigation: + title: Backing up + priority: 600 +--- + +# Backing up your OpenProject installation + +We advise to backup your OpenProject installation regularly — especially before upgrading to a newer version. + +## What should be backed up + +In general the following parts of your OpenProject installation should be backed up: + +- Data stored in the database +- Configuration files +- Uploaded files (attachments) +- Repositories (typically subversion) if applicable + +## Packaged installation (DEB/RPM) + +The DEB/RPM packages provide a backup tool which can be used to take a snaphsot +of the current OpenProject installation. This tool will create a backup of +all parts mentioned above. The backup tool is used by executing the following +command: + +``` +sudo openproject run backup +``` + +The command will create backup files in the following location on your system: + +``` +/var/db/openproject/backup +``` + +The content of that directory should look very similar to the following (depending on your database engine, you will see either a `mysql-dump-.sql.gz` or a `postgresql-dump-` file). + +``` +root@test-packager-backup:/opt/openproject# ls -l /var/db/openproject/backup/ +total 24 +-rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz +-rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz +-rw-r----- 1 openproject openproject 8298 Apr 8 09:55 postgres-dump-20150408095521.sql.gz +-rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz +``` + +You should then copy those dump files to a secure location, for instance an S3 bucket or some sort of backup server. diff --git a/help/installation-and-operations/operation/reconfiguring.md b/help/installation-and-operations/operation/reconfiguring.md new file mode 100644 index 0000000000..c34b90b7be --- /dev/null +++ b/help/installation-and-operations/operation/reconfiguring.md @@ -0,0 +1,25 @@ +--- +sidebar_navigation: + title: (Re)configuring + priority: 800 +--- + +# (Re)configuring OpenProject + +## Packaged installation + +For packaged installations, you can restart the cofniguration process by issuing the following command on the server where OpenProject runs: + +``` +sudo openproject reconfigure +``` + +This will restart the installation wizard, and allow you to modify any of the choices that you previously selected. If a configuration options doesn't need to be modified, just hit `ENTER` to proceed to the next screen. + +## Docker installation + +For docker-based installations, you should update the environment file passed to the `--env-file` docker option, and issue the following command: + +``` +docker restart openproject +``` diff --git a/help/installation-and-operations/operation/restoring.md b/help/installation-and-operations/operation/restoring.md new file mode 100644 index 0000000000..c85ca44ca5 --- /dev/null +++ b/help/installation-and-operations/operation/restoring.md @@ -0,0 +1,75 @@ +--- +sidebar_navigation: + title: Restoring + priority: 500 +--- + +# Restoring an OpenProject backup + +## Packaged installation (DEB/RPM) + +Assuming you have a backup of all the OpenProject files at hand (see the [Backing up](../backing-up) guide), here is how you would restore your OpenProject installation from that backup. + +As a reference, we will assume you have the following dumps on your server, located in `/var/db/openproject/backup`: + +``` +-rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz +-rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz +-rw-r----- 1 openproject openproject 8298 Apr 8 09:55 postgres-dump-20150408095521.sql.gz +-rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz +``` + +### Stop the processes + +First, it is a good idea to stop the OpenProject instance: + +``` +sudo service openproject stop +``` + +### Restoring assets + +Untar the attachments to their destination: + +``` +tar xzf /var/db/openproject/backup/attachments-20150408095521.tar.gz -C /var/db/openproject/files/ +``` + +Untar the configuration to its destination: + +``` +tar xzf /var/db/openproject/backup/conf-20150408095521.tar.gz -C /etc/openproject/ +``` + +Untar the repositories to their destination: + +``` +tar xzf /var/db/openproject/backup/svn-repositories-20150408095521.tar.gz -C /var/db/openproject/repositories +``` + +### Restoring the database + +Note: in this section, the ``, `` and `` variables that appear below have to be replaced with +the values that are contained in the `DATABASE_URL` setting of your +installation. This setting can be seen by running: + +First, get the necessary details about your database: + +``` +openproject config:get DATABASE_URL +#=> e.g.: postgres://dbusername:dppassword@dbhost:dbport/dbname +``` + +Then, to restore the PostgreSQL dump please use the `psql` command utilities: + +``` +zcat /var/db/openproject/backup/postgres-dump-20150408095521.sql.gz | psql -h -u -W +``` + +### Restart the OpenProject processes + +Finally, restart all your processes as follows: + +``` +sudo service openproject restart +``` diff --git a/help/installation-and-operations/packaged/README.md b/help/installation-and-operations/packaged/README.md index d6f9b7b6ea..efc218353a 100644 --- a/help/installation-and-operations/packaged/README.md +++ b/help/installation-and-operations/packaged/README.md @@ -1,11 +1,14 @@ --- sidebar_navigation: - title: Packaged installation - priority: 300 + title: Packages + priority: 400 --- +# Packaged installation (DEB/RPM) -# Packaged installation - -TODO +The packaged installation is the recommended way to install OpenProject. Follow the instructions detailed in the following guides to get OpenProject running on your own server: +| Main Topics | Description | +| ----------- | :---------- | +| [Installation](./installation) | How to install OpenProject from DEB/RPM packages | +| [Initial configuration](./configuration) | How to perform the initial configuration of OpenProject | diff --git a/help/installation-and-operations/packaged/backup.md b/help/installation-and-operations/packaged/backup.md deleted file mode 100644 index 29a506e3d5..0000000000 --- a/help/installation-and-operations/packaged/backup.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -sidebar_navigation: - title: Backup Guide - priority: 50 ---- - -# Packaged installation backup guide - - - -We advise to backup your OpenProject installation regularly — especially before upgrading to a newer version. - -## What should be backed up - -In general the following parts of your OpenProject installation should be backed up: - -- Data stored in the database -- Configuration files -- Uploaded files (attachments) -- Repositories (typically subversion) if applicable - -## How to backup - -The DEB/RPM packages provide a backup tool which can be used to take a snaphsot -of the current OpenProject installation. This tool will create a backup of -all parts mentioned above. The backup tool is used by executing the following -command: - -``` -sudo openproject run backup -``` - -The command will create backup files in the following location on your system - -``` -/var/db/openproject/backup -``` - -The content of that directory should look very similar to the following (depending on your used database, you will see either a `mysql-dump-.sql.gz` or a `postgresql-dump-` file). - -```bash -root@test-packager-backup:/opt/openproject# ls -l /var/db/openproject/backup/ -total 24 --rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz --rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz --rw-r----- 1 openproject openproject 8298 Apr 8 09:55 mysql-dump-20150408095521.sql.gz --rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz -``` - - - -## How to restore - -The backup created with the tool consists of four parts -which are all compressed using `gzip`. Except the database dump these parts -can be restored by decompressing the `*.tar.gz` files and copy the content to the -proper location. The command to untar and unzip the `*.tar.gz` files looks like -this (using sample file names from above): - -```bash -tar vxfz attachments-20150408095521.tar.gz -``` - - - -### Database - -The ``, `` and `` variables have to be replaced with -the values that are container in the `DATABASE_URL` setting of your -installation. This setting can be seen by running: - -``` -openproject config:get DATABASE_URL -#=> e.g.: mysql2://dbusername:dbpassword@dbhost:dbport/dbname -``` - - - -#### PostgreSQL - -To restore the PostgreSQL dump please use the `pg_restore` command utilities. - - - -```bash -pg_restore -h -u -W -``` - - - -First the dump has to be extracted (unzipped) and then restored. The command -used should look very similar to this: - -#### MySQL - - - -To restore the MySQL dump it is recommended to use the `mysql` command line client. - -First the dump has to be extracted (unzipped) and then restored. The command -used should look very similar to this: - -```bash -zcat mysql-dump-20150408095521.sql.gz | mysql -u -h -p -``` diff --git a/help/installation-and-operations/packaged/configuration.md b/help/installation-and-operations/packaged/configuration.md new file mode 100644 index 0000000000..a55adb9699 --- /dev/null +++ b/help/installation-and-operations/packaged/configuration.md @@ -0,0 +1,166 @@ +--- +sidebar_navigation: + title: Initial configuration + priority: 100 +--- + +# Initial configuration of your packaged installation + +After you have successfully installed the OpenProject package ([see the installation guide](../installation)), you can now perform the initial configuration of OpenProject, using the wizard that ships with the OpenProject package. + +## Prerequisites + +- If you wish to connect to an existing database server instead of setting up a local database server, please make sure to have your database hostname, port, username and password ready. The database username used to connect to the existing database must have the CREATE DATABASE privilege. + +- If you want to enable HTTPS, then you will need to provide the path (on the server) to your certificate file, private key file, and CA bundle file. + +## Step 0: start the wizard + +To start the configuration wizard, please run the following command with `sudo`, or as root: + +``` +sudo openproject configure +``` + +**Notes:** + +* In case you mistype or need to correct a configuratin option, you can always safely cancel the configuration wizard by pressing `CTRL+C` and restart it by running `sudo openproject reconfigure`. + +* Every time you will run the OpenProject wizard, your choices will be persisted in a configuration file at `/etc/openproject/installer.dat` and subsequent executions of `sudo openproject configure` will re-use these values, only showing you wizard steps for options you have not yet selected an option for. + +* In case you want to run through all wizard options again, you can do so by executing `sudo openproject reconfigure`. This will show all wizard steps, but again keep values you entered before showing in the input fields. You can skip dialogs you do not want to change simply by confirming them with `ENTER`. + +## Step 1: PostgreSQL database configuration + +The first dialog in the wizard allows you to choose an option for the PostgreSQL database connection: + +![01-postgres](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/01-postgres.png?raw=true) + +The dialog allows you to choose from three options: + +### Install a new PostgreSQL server and database locally (default) + +Choose this option if you want OpenProject to set up and configure a local database server manually. This is the best choice if you are unfamiliar with adminstering databases, or do not have a separate PostgreSQL database server installed that you want to connect to. + +### Use an existing PostgreSQL database + +Choose this option if you have a PostgreSQL database server installed either on the same host as the OpenProject package is being installed on, or on another server you can connect to from this machine. + +The wizard will show you multiple additional steps in this case to enter the hostname, username & password as well as the database name for the PostgreSQL database. + +### Skip (not recommended) + +The wizard will not try to connect to any database. You will have to specify a database manually thorugh the `DATABASE_URL` environment variable. If you choose skip and did not set a `DATABASE_URL`, the configuration process will fail. + +You can set this `DATABASE_URL` parameter yourself to a PostgreSQL database URL. + +``` +sudo openproject config:set DATABASE_URL="postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] +``` + +## Step 2: Apache2 web server + +OpenProject comes with an internal ruby application server, but this server only listens on a local interface. To receive connections from the outside world, it needs a web server that will act as a proxy to forward incoming connections to the OpenProject application server. + +This wizard step allows you to auto-install an Apache2 web server to function as that proxy. + +![02a-apache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02a-apache.png?raw=true) + +The available options are: + +### **Install Apache2 web server** (default) + +We recommend that you let OpenProject install and configure the outer web server, in which case we will install an Apache2 web server with a VirtualHost listening to the domain name you specify, optionally providing SSL/TLS termination. + +### **Skip** (not recommended) + +The installer will not set up an external web server for accessing. You will need to either install and set up a web server such as Apache2 or Nginx to function as the web server forwarding to our internal server listeing at `localhost:6000` by proxying. + +Only choose this option if you have a local Apache2 installed that the OpenProject package may not control, or need to use a different web server such as Nginx. Please note that not all functionality (especially regarding Repositories) are supported on Nginx. + +When installing with an existing Apache2, you can use our [installation wizard templates](https://github.com/pkgr/addon-apache2/tree/master/conf) for guidance on how to set up the integration. [For a minimal nginx config, please see this gist](https://gist.github.com/seLain/375d16ccd4542e3727e97a7478187d3a) as as starting point. + +In case you select to auto-install Apache2, multiple dialogs will request the parameters for setting it up. + +**Domain name** + +Enter the fully qualified domain where your OpenProject installation will be reached at. This will become the `ServerName` of your apache VirtualHost and is also used to generate full links from OpenProject, such as in emails. + +![02b-hostname](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02b-hostname.png?raw=true) + +**Server path prefix** + +If you wish to install OpenProject under a server path prefix, such as `yourdomain.example.com/openproject`, please specify that prefix here with a leading slash. For example: `/openproject`. If OpenProject should respond to `http(s)://yourdomain.example.com` as specified in the previous dialog, simply leave this dialog empty and confirm by pressing `ENTER`. + +![02c-prefix](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02c-prefix.png?raw=true) + +**SSL/TLS configuration** + +OpenProject can configure Apache to support HTTPS (SSL/TLS). If you have SSL certificates and want to use SSL/TLS (recommended), select **Yes**. + +In that case, you will be shown three additional dialogs to enter the certificate details: + +1. The absolute SSL certificate path +2. The absolute SSL private key path +3. The path to the Certificate Authority bundle for the certificate (optional, leave empty unless needed) + +![02d-ssl](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02d-ssl.png?raw=true) + +## Step 3: SVN/Git integration server + +If you have selected to auto-install an Apache2 web server, you will be asked whether you want to install Git and Subversion repository support. In case you do not need it or when in doubt, choose **Skip** for both options. + +For more information, [see our help on repositories](https://www.openproject.org/help/repository/) + +![03-repos](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/03-repos.png?raw=true) + +## Step 4: Outgoing email configuration + +OpenProject requires a setup for sending outgoing emails for notifications, such as updates on work packages, password resets, or other notifications you and your users receive. + +![04-mail](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/04-mail.png?raw=true) + +The wizard supports the following options: + +### **Sendmail** (default) + +Uses a local sendmail installation or sets up a local-only postfix MTA in case you do not have sendmail. + +Easiest setup as it does not require an SMTP configuration, but your Mails may not be delivered consistently depending on your mail accounts or firewall setup. + +### **SMTP** (recommended for production systems) + +Allows you to connect to a SMTP host through authentication types `NONE`, `PLAIN,` `LOGIN`, or `CRAM-MD5`. Use this if you have a dedicated mail account to use for delivering OpenProject mail, or when sendmail does not work due to your local firewall / mail relay setup. + +### **Skip** (not recommended) + +Does not set up mail configuration. You can configure the mail setup in OpenProject by visiting `openproject.example.com/settings?tab=notifications` in your installation. For more information, [visit our help page on this topic](https://www.openproject.org/help/system-settings/email-notification-settings/). + +## Step 5: Administrator email + +The wizard will ask you for an administrative email address so that it can create the administrator account with that email for the initial login. Enter your email address to have it tied to the admin account. + +![05-admin](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/05-admin.png?raw=true) + +## Step 6: Memcached server + +OpenProject heavily relies on caching, which is why the wizard suggests you to install a local memcached server the OpenProject instances can connect to. You should always set this to `install` unless you have a reason to configure another caching mechanism - for example when configuring multiple shared instances of OpenProject. + +![06-cache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/06-cache.png?raw=true) + +## Result + +With this last step confirmed, the OpenProject wizard will complete, and apply all the configuration options that you have just selected. This might take a few minutes depending on your machine and internet connection, as OpenProject might need to install additional packages (such as the web server, database) depending on your selections. + +In case this process crashes or exits with an obvious error, please keep the output and send your configuration from`/etc/openproject/installer.dat` (removing any passwords from it) to us at support@openproject.com , or [reach out to the community forums](https://community.openproject.com/projects/openproject/forums). + +When this process completes, it will have started the internal application and web servers, the background jobs to process work-intensive jobs, and set up the connection to the database. + +You should be able to reach the OpenProject instance by visiting your installation at `http:///`. + +You can then log in using the default user/password combination: + +* username = `admin` +* password = `admin` + +You will be asked to change this password immediately after the first login. diff --git a/help/installation-and-operations/packaged/installation.md b/help/installation-and-operations/packaged/installation.md index 42fd07585c..91a214a43b 100644 --- a/help/installation-and-operations/packaged/installation.md +++ b/help/installation-and-operations/packaged/installation.md @@ -1,40 +1,32 @@ --- sidebar_navigation: - title: Installation Guide + title: Installation priority: 200 --- -# Packaged Installation Guide +# Installation of OpenProject with DEB/RPM packages -The packaged installation of OpenProject is the easiest way to install and maintain OpenProject, provided a supported distribution exists and you can allocate an isolated server for OpenProject. The package will: +The packaged installation of OpenProject is the recommended way to install and maintain OpenProject using DEB or RPM packages. -- guide you through all required steps +The package will: -- install all required libraries and dependencies +- guide you through all the required steps + +- install all the required libraries and dependencies - install a local PostgreSQL database or allow you to connect to an existing PostgreSQL database -- allow you to install and configure an outer Apache web server +- allow you to install and configure an outer Apache web server (recommended) -- setup SSL/TLS encryption for the Apache server +- setup SSL/TLS encryption for the Apache server (optional) -- configure repositories (Git/SVN) +- configure repositories (Git/SVN) (optional) - configure email settings - - - - -## Supported distributions - - - -The packaged installation is provided for the following distributions: - - +The package is available for the following Linux distributions: -| Distribution (64 bits only) | Identifier | init system | +| Distribution (**64 bits only**) | Identifier | init system | | ------------------------------- | ------------ | ----------- | | CentOS/RHEL 7.x | centos-7 | systemd | | Debian 9 Stretch | debian-9 | systemd | @@ -43,608 +35,149 @@ The packaged installation is provided for the following distributions: | Ubuntu 16.04 Xenial Xerus | ubuntu-16.04 | upstart | | Ubuntu 18.04 Bionic Beaver | ubuntu-18.04 | systemd | +Please ensure that you are running on a 64bit system before proceeding with the installation. You can check by running the `uname -i` command on the target server and verifying that it outputs `x86_64`: +``` +$ uname -i +x86_64 +``` -# Install the OpenProject package - - - -As the first step, you will need to add the OpenProject package source to the package manager of your distribution. Please follow the steps with your root user (or with `sudo` if your distribution supports it) according to your distribution: - +Also, please note that the packaged installation works best when running on a dedicated server or virtual machine, as we cannot ensure that the components installed and configured by the OpenProject installer will work on systems that have been already customized. -
+## Installation -### Ubuntu 16.04. +The first step of the installation is to add the OpenProject package source to the package manager of your distribution (`apt`, `yum`, or `zypper`). -**1. Import the packager.io repository signing key** +### Ubuntu 18.04 -Import the PGP key used to sign our packages. Since we're using the *packager.io* platform to distribute our packages, both package source and signing key are tied to their service. +Import the PGP key used to sign our packages: -```bash +``` wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - ``` -**2. Add the OpenProject package source** +Add the OpenProject package source: ``` sudo wget -O /etc/apt/sources.list.d/openproject.list \ - https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/16.04.repo + https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/18.04.repo ``` -**3. Install the OpenProject Community Edition package** - -Using the following commands, apt will check the new package source and install the package and all required dependencies. +Download the OpenProject package: -```bash -apt-get update -apt-get install openproject +``` +sudo apt-get update +sudo apt-get install openproject ``` -
-
- -### Ubuntu 18.04 +Then finish the installation by reading the [*Initial configuration*][initial-config] section. -**1. Import the packager.io repository signing key** +### Ubuntu 16.04 -Import the PGP key used to sign our packages. Since we're using the *packager.io* platform to distribute our packages, both package source and signing key are tied to their service. +Import the PGP key used to sign our packages: -```bash -wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - ``` - -**2. Ensure that universe package source is added** - -You may run into issues trying to install the `dialog` package in Ubuntu 18.04. To resolve this, please ensure you have the universe APT source - -```bash -sudo add-apt-repository universe +wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - ``` -**3. Add the OpenProject package source** +Add the OpenProject package source: ``` sudo wget -O /etc/apt/sources.list.d/openproject.list \ - https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/18.04.repo + https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/16.04.repo ``` -**4. Install the OpenProject Community Edition package** - -Using the following commands, apt will check the new package source and install the package and all required dependencies. +Download the OpenProject package: -```bash -apt-get update -apt-get install openproject +``` +sudo apt-get update +sudo apt-get install openproject ``` -
-
- -### Debian 9 +Then finish the installation by reading the [*Initial configuration*][initial-config] section. -**1. Import the packager.io repository signing key** +### Debian 10 -Import the PGP key used to sign our packages. Since we're using the *packager.io* platform to distribute our packages, both package source and signing key are tied to their service. +Import the PGP key used to sign our packages: -```bash +``` wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - ``` -**2. Add the OpenProject package source** +Add the OpenProject package source: ``` -wget -O /etc/apt/sources.list.d/openproject.list \ - https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/9.repo +sudo wget -O /etc/apt/sources.list.d/openproject.list \ + https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/10.repo ``` -**3. Install the OpenProject Community Edition package** - -Using the following commands, apt will check the new package source and install the package and all required dependencies. +Download the OpenProject package: -```bash -apt-get update -apt-get install openproject +``` +sudo apt-get update +sudo apt-get install openproject ``` -
-
- -### Debian 10 +Then finish the installation by reading the [*Initial configuration*][initial-config] section. -**1. Import the packager.io repository signing key** +### Debian 9 -Import the PGP key used to sign our packages. Since we're using the *packager.io* platform to distribute our packages, both package source and signing key are tied to their service. +Import the PGP key used to sign our packages: -```bash +``` wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - ``` -**2. Add the OpenProject package source** +Add the OpenProject package source: ``` -wget -O /etc/apt/sources.list.d/openproject.list \ - https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/10.repo +sudo wget -O /etc/apt/sources.list.d/openproject.list \ + https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/9.repo ``` -**3. Install the OpenProject Community Edition package** +Download the OpenProject package: -Using the following commands, apt will check the new package source and install the package and all required dependencies. - -```bash -apt-get update -apt-get install openproject +``` +sudo apt-get update +sudo apt-get install openproject ``` -
-
+Then finish the installation by reading the [*Initial configuration*][initial-config] section. -### Centos 7 +### CentOS 7 / RHEL 7 -**1. Add the OpenProject package source** +Add the OpenProject package source: ``` sudo wget -O /etc/yum.repos.d/openproject.repo \ https://dl.packager.io/srv/opf/openproject/stable/10/installer/el/7.repo ``` -**2. Install the OpenProject Community Edition package** +Download the OpenProject package: -Using the following command, yum will install the package and all required dependencies. - -```bash +``` sudo yum install openproject ``` -
-
+Then finish the installation by reading the [*Initial configuration*][initial-config] section. ### SLES 12 -**1. Add the OpenProject package source** +Add the OpenProject package source: ``` wget -O /etc/zypp/repos.d/openproject.repo \ https://dl.packager.io/srv/opf/openproject/stable/10/installer/sles/12.repo ``` -The package source is now registered as `openproject`. - -**2. Install the OpenProject Community Edition package** - -Using the following command, zypper will install the package and all required dependencies. - -```bash -zypper install openproject -``` - -
- - - -# Package configuration - -The last but most important step to your OpenProject installation is the configuration wizard. It will set up the connection to a database and configure the application according to your environment. - -The wizard can be activated through the command `sudo openproject configure` and will guide you through all necessary steps to set up your OpenProject installation. - -Once you have configured this wizard, your selection will be persisted in a configuration file in `/etc/openproject/installer.dat` and subsequent executions of `sudo openproject configure` will re-use these values, only showing you wizard steps for options you have not yet selected an option for. - -In case you want to run through all wizard options again, you can do so by executing `sudo openproject reconfigure`. This will show all wizard steps, but again keep values you entered before showing in the input fields. You can skip dialogs you do not want to change simply by confirming them with `ENTER`. - - - -## Step 0: Prepare and the configuration script - -You are now ready to configure your OpenProject instance. Please prepare necessary parameters: - -- If you wish to connect to an existing database, have your hostname / user:password and database name ready -- If you have SSL/TLS certificates ready, please note the paths to the certificate, key file and CA bundle - - - -To start the configuration wizard, please run the following command with `sudo`, or as root. - -```bash -sudo openproject configure -``` - - - -**Note:** In case you mistyped or need to correct a configuratin option, you can always safely cancel the configuration wizard by pressing `CTRL+C` and restart verything by running `openproject reconfigure`. This happens often due to waiting on setups being cleared, such as DNS entries for your domain or SSL/TLS certificates that need to be set up later. - -## Step 1: PostgreSQL database configuration - -The first dialog in the wizard allows you to choose an option for the PostgreSQL database connection. - - - -![01-postgres](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/01-postgres.png?raw=true) - - - -The dialog allows you to choose from three options: - - - -### Install a new PostgreSQL server and database locally (default) - -Choose this option if you want OpenProject to set up and configure a local database server manually. This is the best choice if you are unfamiliar with adminstering databases, or do not have a separate PostgreSQL database server installed that you want to connect to. - - - -### Use an existing PostgreSQL database - -Choose this option if you have a PostgreSQL database server installed either on the same host as the OpenProject package is being installed on, or on another server you can connect to from this machine. - -The wizard will show you multiple additional steps in this case to enter the hostname, username & password as well as the database name for the PostgreSQL database. - - - -### Skip (not recommended) - -The wizard will not try to connect to any database. You will have to specify a database manually thorugh the `DATABASE_URL` environment variable. If you choose skip and did not set a `DATABASE_URL`, the configuration process will fail. - -You can set this `DATABASE_URL` parameter yourself to a PostgreSQL database URL. - -``` -openproject config:set DATABASE_URL="postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] -``` - - - -## Step 2: Apache2 web server - -OpenProject comes with an internal ruby application server, but that will run only on a local interface. It needs an external web server handling connections from the outside world and pass those to the application server with a proxy / reverse-proxy configuration. - -This wizard step allows you to auto-install an Apache2 web server to function as that external web server. - -![02a-apache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02a-apache.png?raw=true) - - - -**Install Apache2 web server** (default) - -We recommend that you let OpenProject install and configure the outer web server, in which case we will install an Apache2 web server with a VirtualHost listening to the domain name you specify, optionally providing SSL/TLS termination. - - - -**Skip** (not recommended) - -The installer will not set up an external web server for accessing. You will need to either install and set up a web server such as Apache2 or Nginx to function as the web server forwarding to our internal server listeing at `localhost:6000` by proxying. - -Only choose this option if you have a local Apache2 installed that the OpenProject package may not control, - -or need to use a different web server such as Nginx. Please note that not all functionality (especially regarding Repositories) are supported on Nginx. - -When installing with an existing Apache2, you can use our [installation wizard templates](https://github.com/pkgr/addon-apache2/tree/master/conf) for guidance on how to set up the integration. [For a minimal nginx config, please see this gist](https://gist.github.com/seLain/375d16ccd4542e3727e97a7478187d3a) as as starting point. - -(Please help us improve this section with your feeback and experiences of integrating OpenProject in other servers. [You can find this documentation on GitHub](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/2-configuration.md)). - - - -In case you select to auto-install Apache2, multiple dialogs will request the parameters for setting it up. - - - -**Domain name** - -Enter the fully qualified domain where your OpenProject installation will be reached at. This will become the `ServerName` of your apache VirtualHost and is also used to generate full links from OpenProject, such as in emails. - -![02b-hostname](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02b-hostname.png?raw=true) - - - -**Server path prefix** - -If you wish to install OpenProject under a server path prefix, such as `yourdomain.example.com/openproject`, please specify that prefix here with a leading slash. For example: `/openproject`. If OpenProject should respond to `http(s)://yourdomain.example.com` as specified in the previous dialog, simply leave this dialog empty and confirm by pressing `ENTER`. - -![02c-prefix](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02c-prefix.png?raw=true) - - - - +Download the OpenProject package: -**SSL/TLS configuration** - -OpenProject can configure the necessary steps in your VirtualHost to terminate SSL/TLS connections at the web server. If you have SSL certificates and want to use SSL/TLS (recommended), select **Yes**. - -In that case, you will be shown three additional dialogs to enter the certificate details: - -1. The absolute SSL certificate path -2. The absolute SSL private key path -3. (optional, leave empty unless needed) The path to the Certificate Authority bundle for the certificate - -![02d-ssl](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02d-ssl.png?raw=true) - - - -## Step 3: SVN/Git integration server - -If you have selected to auto-install an Apache2 web server, you will be asked whether you want to install Git and Subversion repository support. In case you do not need it or when in doubt, choose **Skip** for both options. - -For more information, [see our help on repositories](https://www.openproject.org/help/repository/) - -![03-repos](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/03-repos.png?raw=true) - - - -## Step 4: Outgoing email configuration - -OpenProject requires a setup for sending outgoing emails for notifications, such as updates to created tickets or other notifications you and your users receive. - -![04-mail](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/04-mail.png?raw=true) - - - -**Sendmail** (default) - -Uses a local sendmail installation or sets up a local-only postfix MTA in case you do not have sendmail. - -Easiest setup as it does not require an SMTP configuration, but your Mails may not be delivered consistently depending on your mail accounts or firewall setup. - -**SMTP** (recommend for production systems) - -Allows you to connect to a SMTP host through authentication types `NONE`, `PLAIN,` `LOGIN`, or `CRAM-MD5`. Use this if you have a dedicated mail account to use for delivering OpenProject mail, or when sendmail does not work due to your local firewall / mail relay setup. - -**Skip** (not recommended) - -Does not set up mail configuration. You can configure the mail setup in OpenProject by visiting `openproject.example.com/settings?tab=notifications` in your installation. For more information, [visit our help page on this topic](https://www.openproject.org/help/system-settings/email-notification-settings/). - - - -## Step 5: Administrator email - -The wizard will ask you for an administrative email address to create the administrator account with for initial login. Enter your email address to have it tied to the admin account. - -![05-admin](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/05-admin.png?raw=true) - - - -### Last step: Memcached server - -OpenProject heavily relies on caching, which is why the wizard suggests you to install a local memcached server the OpenProject instances can connect to. You should always set this to `install` unless you have a reason to configure another caching mechanism - for example when configuring multiple shared instances of OpenProject. - -![06-cache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/06-cache.png?raw=true) - - - -With this last step confirmed, the OpenProject wizard will complete, and apply all the configuration options that you have just chosen. This might take a few minutes depending on your machine and internet connection, as OpenProject might need to install additional packages (such as the web server, database) depending on your selections. - -In case this process crashes or exits with an obvious error, please keep the output and send your configuration from`/etc/openproject/installer.dat` (removing any passwords from it) to us at support@openproject.com , or [reach out to the community forums](https://community.openproject.com/projects/openproject/forums). - -When this process completes, it will have started the internal application and web servers, the background jobs to process work-intensive jobs, and set up the connection to the database. - -You can log into the instance initially by visiting your installation at `http:///` and log in initially using the user/password combination **admin/admin.** You will be asked to change this password immediately after the first login. - -This concludes the initial configuration, the following sections will detail the commands you can use to additionall configure and/or maintain your installation. - - - -## Managing your OpenProject installation - -The openproject package comes with a command line tool to help manage the -application. To see all possible command options of this tool you can run: - - admin@openproject-demo:~# sudo openproject - Usage: - openproject run COMMAND [options] - openproject scale PROCESS=NUM - openproject logs [--tail|-n NUMBER] - openproject config:get VAR - openproject config:set VAR=VALUE - openproject config:unset VAR - openproject reconfigure - openproject restart [PROCESS] - -In the rest of this section we'll go over some of the most important commands. - -#### Run commands like rake tasks or rails console - -The openproject command line tool supports running rake tasks and known scripts -like the rails console: - - # Get the current version of OpenProject - sudo openproject run bundle exec rake version - # Or spawn an interactive console - sudo openproject run console - # or a rake task - sudo openproject run rake db:migrate - # or check the version of ruby used by openproject - sudo openproject run ruby -v - -#### Show logs - -The command line tool can also be used to see the log information. The most -typically use case is to show/follow all current log entries. This can be -accomplished using the the `–tail` flag. See example below: - - sudo openproject logs --tail - -Note: - -* On distributions that are based on systemd, all the logs are sent to journald, so you can also display them via `journalctl`. -* On older distributions that use either sysvinit or upstart, all the logs are stored in `/var/log/openproject/`. - -#### Scaling the number of web workers - -Depending on your free RAM on your system, we recommend you raise the default number of workers. The default from 9.0.3 onwards is four worker processes. Each worker will take roughly 300-400MB RAM. - -We recommend at least four workers. Please check your current worker count with - -```bash - sudo openproject config:get OPENPROJECT_WEB_WORKERS ``` - -If it returns nothing, the default worker count of `4` applies. To increase or decrease the worker count, call - -```bash - sudo openproject config:set OPENPROJECT_WEB_WORKERS=number +sudo zypper install openproject ``` -Where `number` is a positive number between 1 and `round(AVAILABLE_RAM * 1.5)`. - -After changing these values, call `sudo openproject configure` to apply it to the web server. - -#### Reconfigure the application - -At any point in time, you can reconfigure the whole application by re-running the installer with the following command: - - sudo openproject reconfigure - -The command above will bring up the installation wizard again. Please be aware that it will start the configuration/installation process from scratch. You can choose to modify existing entries, or just leave them as they are if you want to reuse them (note that passwords will appear as "blank" entries in their -respective input fields, but you don't need to enter them again if don't want to modify them). - -#### Upgrading the application - -As openproject is a system package, it will be automatically updated when you install your package updates. - -After you have just updated your OpenProject version, you should run `openproject configure` (see section below), which would automatically reuse your previous configuration, and only asks for your input if new configuration options are available. - -For a complete guide on upgrading your OpenProject packaged installation, [please see this guide](upgrading). - -#### Inspect the existing configuration - -You can list all of the environment variables accessible to the application by running: - - sudo openproject config - # this will return something like: - DATABASE_URL=mysql2://openproject:9ScapYA1MN7JQrPR7Wkmp7y99K6mRHGU@127.0.0.1:3306/openproject - SECRET_TOKEN=c5aa99a90f9650404a885cf5ec7c28f7fe1379550bb811cb0b39058f9407eaa216b9b2b22d27f58fb15ac21adb3bd16494ebe89e39ec225ef4627db048a12530 - ADMIN_EMAIL=mail@example.com - EMAIL_DELIVERY_METHOD=smtp - SMTP_DOMAIN=example.com - SMTP_HOST=smtp.example.com - SMTP_PASSWORD=mail - SMTP_PORT=25 - SMTP_URL=smtp://mail:mail@smtp.example.com:25/example.com - SMTP_USERNAME=mail - SMTP_ENABLE_STARTTLS_AUTO=true - SMTP_AUTHENTICATION=plain - WEB_CONCURRENCY=4 - WEB_TIMEOUT=15 - RAILS_CACHE_STORE=memcache - SESSION_STORE=cache_store - - - -# Frequently asked questions - FAQ - -## How can I install an OpenProject plugin? - -Our [official installation page][install-page] has instructions on how to customize your OpenProject installation. -Please note that customization is not yet supported for Docker-based installations. - -[install-page]: https://www.openproject.org/download-and-installation/ - - - -## How to migrate from Bitnami to the official OpenProject installation packages? - -Please follow the following steps: - -1. Make a dump of your bitnami database to export your data. You can refer to the [Bitnami documentation][bitnami-mysql]. -1. Make a dump of files your might have uploaded. You can refer to the [Bitnami documentation][bitnami-backup] to perform a full dump. -1. Copy both dumps to the server you want to install OpenProject on. -1. Install OpenProject using the packaged installation. -1. By default, this will allow you to install a PostgreSQL database, which we recommend. You can migrate your data from MySQL using https://pgloader.io -1. Import the dump into your new database. You can get your configuration by running `sudo openproject config:get DATABASE_URL` -1. Extract the bitnami backup, and copy your file assets into the relevant directory (e.g. in `/var/db/openproject/files` for uploaded files) -1. Restart OpenProject - -[bitnami-mysql]: https://docs.bitnami.com/installer/components/mysql/ -[bitnami-backup]: https://docs.bitnami.com/installer/apps/openproject/ - - - -## Can I use NginX instead of Apache webserver? - -Yes, but you will lose the ability to enable Git/SVN repository integration. Note that the OpenProject installer does not support NginX, so you will have to ask to disable the Apache2 integration when running the installer, and then configure NginX yourself so that it forwards traffic to the OpenProject web process (listening by default on 127.0.0.1:6000). If using SSL/TLS, please ensure you set the header value `X-Forwarded-Proto https` so OpenProject can correctly produce responses. [For more information, please visit our forums](https://community.openproject.com/projects/openproject/boards). - - - -## Can I use MySQL instead of PostgreSQL? - -OpenProject has traditionally supported both MySQL and PostgreSQL, but in order to optimize for performance and SQL functionality, it is unfeasible to support both DBMS that are becoming more and more disjunct when trying to use more modern SQL features. This shift has started some years ago when full-text search was added for PostgreSQL, but at the time MySQL did not yet support it - and as of yet many distributions still do not support MySQL 8 natively. - -This led us to the path of removing support in the upcoming stable releases of OpenProject in order to focus on these goals. [Please see our blog post on the matter for additional notes](https://www.openproject.org/deprecating-mysql-support/). - - - -## How can I migrate my existing MySQL database to PostgreSQL ? - -Older installations of OpenProject are likely installed with a MySQL installation because the installer shipped with an option to auto-install it. With [pgloader](https://pgloader.io), it is trivially easy to convert a dump between MySQL and PostgreSQL installation. [We have prepared a guide](https://www.openproject.org/operations/upgrading/migrating-packaged-openproject-database-postgresql/) on how to migrate to a PostgreSQL database if you previously used MySQL. - - - -## My favorite linux distribution is not listed. What can I do? - -You can either try the manual installation, or ask in the forum whether this could be added to the list of supported distributions. We try to support recent major distributions, but due to maintenance and operations cost cannot freely add to that list. - - - -## What is the better option to run OpenProject in production environments: docker or linux packages? - -We recommend the Linux packages [if you have a compatible distribution](https://www.openproject.org/system-requirements/) and a separate machine for OpenProject, since it will allow for the easiest and most flexible setup. Use a docker-based image either for quickly spinning up an environment or if you have knowledge in setting up and maintaing docker-based installations. - -Please note we currently do not yet provide a docker-compose based image, [please see this ticket for a timeline](https://community.openproject.com/wp/30551) and help us contribute one! - - - -## Do you provide different release channels? - -Yes! We release OpenProject in separate release channels that you can try out. For production environments, **always** use the `stable/MAJOR` (e.g., stable/9) package source that will receive stable and release updates. Every major upgrade will result in a source switch (from `stable/7` to `stable/8` for example). - -A closer look at the available branches: - -* [stable/9](https://packager.io/gh/opf/openproject/refs/stable/9): Latest stable releases, starting with 9.0.0 until the last minor and patch releases of 9.X.Y are released, this will receive updates. -* [release/9.0](https://packager.io/gh/opf/openproject/refs/release/9.0): Regular (usually daily) release builds for the current next patch release (or for the first release in this version, such as 9.0.0). This will contain early bugfixes before they are being release into stable. **Do not use in production**. But, for upgrading to the next major version, this can be regarded as a _release candidate channel_ that you can use to test your upgrade on a copy of your production environment. -* [dev](https://packager.io/gh/opf/openproject/refs/dev): Daily builds of the current development build of OpenProject. While we try to keep this operable, this may result in broken code and/or migrations from time to time. Use when you're interested what the next release of OpenProject will look like. **Do not use in production!** - -For more information, please visit our dedicated [page regarding release candidates and channels](https://www.openproject.org/download-and-installation/release-candidate/). - - - -## How to upgrade my OpenProject installation? - -Please refer to the documentation at https://www.openproject.org/operations/upgrading/ - - - -## What skills should I have for the installation? - -If you use the packaged installation, you should have a basic knowledge of Linux and the command-line terminal. - -If you use the docker images, you need to be familiar with Docker and Docker volumes. - - - -## Why don't you support Windows? - -Ruby support on Windows is notoriously difficult, however you might be able to run the Docker image, or use the unofficial Windows stack provided by [Bitnami](https://bitnami.com/stack/openproject/installer). We would welcome feedback and reported experiences on running OpenProject on Windows, please reach out to us if you can contribute some information. - - - -## How to backup and restore my OpenProject installation? - -Please refer to the [backup documentation](backup) for the packaged installation. - - - -## How can I install a free SSL certificate using let's encrypt? - -You can get an SSL certificate for free via Let's Encrypt. -Here is how you do it using [certbot](https://github.com/certbot/certbot): - - curl https://dl.eff.org/certbot-auto > /usr/local/bin/certbot-auto - chmod a+x /usr/local/bin/certbot-auto - - certbot-auto certonly --webroot --webroot-path /opt/openproject/public -d openprojecct.mydomain.com - -This requires your OpenProject server to be available from the Internet on port 443 or 80. -If this works the certificate (`cert.pem`) and private key (`privkey.pem`) will be created under `/etc/letsencrypt/live/openproject.mydomain.com/`. Configure these for OpenProject to use by running `openproject reconfigure` and choosing yes when the wizard asks for SSL. +Then finish the installation by reading the [*Initial configuration*][initial-config] section. -Now this Let's Encryt certificate is only valid for 90 days. To renew it automatically all you have to do is to add the following entry to your crontab (run `crontab -e`): +[initial-config]: ../configuration - 0 1 * * * certbot-auto renew --quiet --post-hook "service apache2 restart" -This will execute `certbot renew` every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate. diff --git a/help/installation-and-operations/packaged/stuff-to-move.md b/help/installation-and-operations/packaged/stuff-to-move.md new file mode 100644 index 0000000000..92032fba9e --- /dev/null +++ b/help/installation-and-operations/packaged/stuff-to-move.md @@ -0,0 +1,228 @@ +## Managing your OpenProject installation + +The openproject package comes with a command line tool to help manage the +application. To see all possible command options of this tool you can run: + + admin@openproject-demo:~# sudo openproject + Usage: + openproject run COMMAND [options] + openproject scale PROCESS=NUM + openproject logs [--tail|-n NUMBER] + openproject config:get VAR + openproject config:set VAR=VALUE + openproject config:unset VAR + openproject reconfigure + openproject restart [PROCESS] + +In the rest of this section we'll go over some of the most important commands. + +#### Run commands like rake tasks or rails console + +The openproject command line tool supports running rake tasks and known scripts +like the rails console: + + # Get the current version of OpenProject + sudo openproject run bundle exec rake version + # Or spawn an interactive console + sudo openproject run console + # or a rake task + sudo openproject run rake db:migrate + # or check the version of ruby used by openproject + sudo openproject run ruby -v + +#### Show logs + +The command line tool can also be used to see the log information. The most +typically use case is to show/follow all current log entries. This can be +accomplished using the the `–tail` flag. See example below: + + sudo openproject logs --tail + +Note: + +* On distributions that are based on systemd, all the logs are sent to journald, so you can also display them via `journalctl`. +* On older distributions that use either sysvinit or upstart, all the logs are stored in `/var/log/openproject/`. + +#### Scaling the number of web workers + +Depending on your free RAM on your system, we recommend you raise the default number of workers. The default from 9.0.3 onwards is four worker processes. Each worker will take roughly 300-400MB RAM. + +We recommend at least four workers. Please check your current worker count with + +```bash + sudo openproject config:get OPENPROJECT_WEB_WORKERS +``` + +If it returns nothing, the default worker count of `4` applies. To increase or decrease the worker count, call + +```bash + sudo openproject config:set OPENPROJECT_WEB_WORKERS=number +``` + +Where `number` is a positive number between 1 and `round(AVAILABLE_RAM * 1.5)`. + +After changing these values, call `sudo openproject configure` to apply it to the web server. + +#### Reconfigure the application + +At any point in time, you can reconfigure the whole application by re-running the installer with the following command: + + sudo openproject reconfigure + +The command above will bring up the installation wizard again. Please be aware that it will start the configuration/installation process from scratch. You can choose to modify existing entries, or just leave them as they are if you want to reuse them (note that passwords will appear as "blank" entries in their +respective input fields, but you don't need to enter them again if don't want to modify them). + +#### Upgrading the application + +As openproject is a system package, it will be automatically updated when you install your package updates. + +After you have just updated your OpenProject version, you should run `openproject configure` (see section below), which would automatically reuse your previous configuration, and only asks for your input if new configuration options are available. + +For a complete guide on upgrading your OpenProject packaged installation, [please see this guide](upgrading). + +#### Inspect the existing configuration + +You can list all of the environment variables accessible to the application by running: + + sudo openproject config + # this will return something like: + DATABASE_URL=mysql2://openproject:9ScapYA1MN7JQrPR7Wkmp7y99K6mRHGU@127.0.0.1:3306/openproject + SECRET_TOKEN=c5aa99a90f9650404a885cf5ec7c28f7fe1379550bb811cb0b39058f9407eaa216b9b2b22d27f58fb15ac21adb3bd16494ebe89e39ec225ef4627db048a12530 + ADMIN_EMAIL=mail@example.com + EMAIL_DELIVERY_METHOD=smtp + SMTP_DOMAIN=example.com + SMTP_HOST=smtp.example.com + SMTP_PASSWORD=mail + SMTP_PORT=25 + SMTP_URL=smtp://mail:mail@smtp.example.com:25/example.com + SMTP_USERNAME=mail + SMTP_ENABLE_STARTTLS_AUTO=true + SMTP_AUTHENTICATION=plain + WEB_CONCURRENCY=4 + WEB_TIMEOUT=15 + RAILS_CACHE_STORE=memcache + SESSION_STORE=cache_store + + + +# Frequently asked questions - FAQ + +## How can I install an OpenProject plugin? + +Our [official installation page][install-page] has instructions on how to customize your OpenProject installation. +Please note that customization is not yet supported for Docker-based installations. + +[install-page]: https://www.openproject.org/download-and-installation/ + + + +## How to migrate from Bitnami to the official OpenProject installation packages? + +Please follow the following steps: + +1. Make a dump of your bitnami database to export your data. You can refer to the [Bitnami documentation][bitnami-mysql]. +1. Make a dump of files your might have uploaded. You can refer to the [Bitnami documentation][bitnami-backup] to perform a full dump. +1. Copy both dumps to the server you want to install OpenProject on. +1. Install OpenProject using the packaged installation. +1. By default, this will allow you to install a PostgreSQL database, which we recommend. You can migrate your data from MySQL using https://pgloader.io +1. Import the dump into your new database. You can get your configuration by running `sudo openproject config:get DATABASE_URL` +1. Extract the bitnami backup, and copy your file assets into the relevant directory (e.g. in `/var/db/openproject/files` for uploaded files) +1. Restart OpenProject + +[bitnami-mysql]: https://docs.bitnami.com/installer/components/mysql/ +[bitnami-backup]: https://docs.bitnami.com/installer/apps/openproject/ + + + +## Can I use NginX instead of Apache webserver? + +Yes, but you will lose the ability to enable Git/SVN repository integration. Note that the OpenProject installer does not support NginX, so you will have to ask to disable the Apache2 integration when running the installer, and then configure NginX yourself so that it forwards traffic to the OpenProject web process (listening by default on 127.0.0.1:6000). If using SSL/TLS, please ensure you set the header value `X-Forwarded-Proto https` so OpenProject can correctly produce responses. [For more information, please visit our forums](https://community.openproject.com/projects/openproject/boards). + + + +## Can I use MySQL instead of PostgreSQL? + +OpenProject has traditionally supported both MySQL and PostgreSQL, but in order to optimize for performance and SQL functionality, it is unfeasible to support both DBMS that are becoming more and more disjunct when trying to use more modern SQL features. This shift has started some years ago when full-text search was added for PostgreSQL, but at the time MySQL did not yet support it - and as of yet many distributions still do not support MySQL 8 natively. + +This led us to the path of removing support in the upcoming stable releases of OpenProject in order to focus on these goals. [Please see our blog post on the matter for additional notes](https://www.openproject.org/deprecating-mysql-support/). + + + +## How can I migrate my existing MySQL database to PostgreSQL ? + +Older installations of OpenProject are likely installed with a MySQL installation because the installer shipped with an option to auto-install it. With [pgloader](https://pgloader.io), it is trivially easy to convert a dump between MySQL and PostgreSQL installation. [We have prepared a guide](https://www.openproject.org/operations/upgrading/migrating-packaged-openproject-database-postgresql/) on how to migrate to a PostgreSQL database if you previously used MySQL. + + + +## My favorite linux distribution is not listed. What can I do? + +You can either try the manual installation, or ask in the forum whether this could be added to the list of supported distributions. We try to support recent major distributions, but due to maintenance and operations cost cannot freely add to that list. + + + +## What is the better option to run OpenProject in production environments: docker or linux packages? + +We recommend the Linux packages [if you have a compatible distribution](https://www.openproject.org/system-requirements/) and a separate machine for OpenProject, since it will allow for the easiest and most flexible setup. Use a docker-based image either for quickly spinning up an environment or if you have knowledge in setting up and maintaing docker-based installations. + +Please note we currently do not yet provide a docker-compose based image, [please see this ticket for a timeline](https://community.openproject.com/wp/30551) and help us contribute one! + + + +## Do you provide different release channels? + +Yes! We release OpenProject in separate release channels that you can try out. For production environments, **always** use the `stable/MAJOR` (e.g., stable/9) package source that will receive stable and release updates. Every major upgrade will result in a source switch (from `stable/7` to `stable/8` for example). + +A closer look at the available branches: + +* [stable/9](https://packager.io/gh/opf/openproject/refs/stable/9): Latest stable releases, starting with 9.0.0 until the last minor and patch releases of 9.X.Y are released, this will receive updates. +* [release/9.0](https://packager.io/gh/opf/openproject/refs/release/9.0): Regular (usually daily) release builds for the current next patch release (or for the first release in this version, such as 9.0.0). This will contain early bugfixes before they are being release into stable. **Do not use in production**. But, for upgrading to the next major version, this can be regarded as a _release candidate channel_ that you can use to test your upgrade on a copy of your production environment. +* [dev](https://packager.io/gh/opf/openproject/refs/dev): Daily builds of the current development build of OpenProject. While we try to keep this operable, this may result in broken code and/or migrations from time to time. Use when you're interested what the next release of OpenProject will look like. **Do not use in production!** + +For more information, please visit our dedicated [page regarding release candidates and channels](https://www.openproject.org/download-and-installation/release-candidate/). + + + +## How to upgrade my OpenProject installation? + +Please refer to the documentation at https://www.openproject.org/operations/upgrading/ + + + +## What skills should I have for the installation? + +If you use the packaged installation, you should have a basic knowledge of Linux and the command-line terminal. + +If you use the docker images, you need to be familiar with Docker and Docker volumes. + + + +## Why don't you support Windows? + +Ruby support on Windows is notoriously difficult, however you might be able to run the Docker image, or use the unofficial Windows stack provided by [Bitnami](https://bitnami.com/stack/openproject/installer). We would welcome feedback and reported experiences on running OpenProject on Windows, please reach out to us if you can contribute some information. + + + +## How to backup and restore my OpenProject installation? + +Please refer to the [backup documentation](backup) for the packaged installation. + + + +## How can I install a free SSL certificate using let's encrypt? + +You can get an SSL certificate for free via Let's Encrypt. +Here is how you do it using [certbot](https://github.com/certbot/certbot): + + curl https://dl.eff.org/certbot-auto > /usr/local/bin/certbot-auto + chmod a+x /usr/local/bin/certbot-auto + + certbot-auto certonly --webroot --webroot-path /opt/openproject/public -d openprojecct.mydomain.com + +This requires your OpenProject server to be available from the Internet on port 443 or 80. +If this works the certificate (`cert.pem`) and private key (`privkey.pem`) will be created under `/etc/letsencrypt/live/openproject.mydomain.com/`. Configure these for OpenProject to use by running `openproject reconfigure` and choosing yes when the wizard asks for SSL. + +Now this Let's Encryt certificate is only valid for 90 days. To renew it automatically all you have to do is to add the following entry to your crontab (run `crontab -e`): + + 0 1 * * * certbot-auto renew --quiet --post-hook "service apache2 restart" + +This will execute `certbot renew` every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate. diff --git a/help/installation-and-operations/system-requirements.md b/help/installation-and-operations/system-requirements.md index 5b3518f9de..d2ad6a1fd8 100644 --- a/help/installation-and-operations/system-requirements.md +++ b/help/installation-and-operations/system-requirements.md @@ -1,3 +1,9 @@ +--- +sidebar_navigation: + title: System requirements + priority: 1000 +--- + # System requirements __Note__: The configurations described below are what we use and test against. diff --git a/help/user-guide/activity.md b/help/user-guide/activity.md index 7b10765b28..ffd0f8e206 100644 --- a/help/user-guide/activity.md +++ b/help/user-guide/activity.md @@ -1,5 +1,5 @@ --- -nav: +sidebar_navigation: title: Activity priority: 890 description: Find out about the Activity within a project diff --git a/help/user-guide/project-overview.md b/help/user-guide/project-overview.md index 6a4f6edcf5..0f4cfbfe69 100644 --- a/help/user-guide/project-overview.md +++ b/help/user-guide/project-overview.md @@ -1,5 +1,5 @@ --- -nav: +sidebar_navigation: title: Project overview priority: 900 description: Learn how to configure a project overview page @@ -9,23 +9,23 @@ keywords: project overview page # Project overview -The **Project overview** page is a dashboard with important project information. You can display relevant information for the team, such as Members, News, Project description, Work package reports, or a project status. +The **Project overview** page is a dashboard with important project information. You can display relevant information for your team, such as members, news, project description, work package reports, or a project status. | Feature | Documentation for | | ------------------------------------------------------------ | ------------------------------------------------------- | | [What is the project overview?](#what-is-the-project-overview?) | What can I do with the project overview page? | -| [Add a widget to the project overview](#add-a-widget-to-the-project-overview) | How to add a new widget to the project overview? | +| [Add a widget to the project overview](#add-a-widget-to-the-project-overview) | How can I add a new widget to the project overview? | | [Available project overview widgets](#available-project-overview-widgets) | What kind of widgets can I add to the project overview? | -| [Re-size and re-order widgets](#re-size-and-re-order-widgets) | How to re-order or re-size the widgets? | -| [Remove widget](#remove-widget-from-project-overview-page) | How to remove widget from project overview page? | +| [Re-size and re-order widgets](#re-size-and-re-order-widgets) | How can I re-order or re-size the widgets? | +| [Remove widget](#remove-widget-from-project-overview-page) | How can I remove widget from project overview page? | ## What is the project overview? -The project overview is a single dashboard page where all important project information can be displayed to have it centrally available for the project team. +The project overview is a single dashboard page where all important project information can be displayed. The idea is to have it centrally available for the whole project team. -You can add project information as widgets to the dashboard and order and re-size the widgets to your need. +You can add project information as widgets to the dashboard and not only order but also re-size the widgets according to your needs. -Also, you can add text widgets, to add custom texts, links and other information to your overview page. +Furthermore, you can add text widgets, custom texts, links and other information to your overview page. Open the project overview by navigating to **Overview** in the project menu on the left. @@ -37,7 +37,7 @@ Open the project overview by navigating to **Overview** in the project menu on t 1. Choose the place where to add the new widget. -To add a widget to the project overview, click on the **+ button** on the top right of the page. Select the place where to add the widget, by clicking on a plus that appear on the page. +To add a widget to the project overview, click on the **+ button** on the top right of the page. Select the place where to add the widget, by clicking on a plus that appears on the top right corner of the page. ![Overview-add-widget](Overview-add-widget-1573564870548.png) @@ -55,7 +55,7 @@ You can add various widgets to your project overview. ### Calendar widget -The calendar widget displays your current work packages in a calendar. It shows work package that are being worked on at the current date. +The calendar widget displays your current work packages in a calendar. It shows work packages that are being worked on at the current date. ![calendar](image-20191112142555628.png) @@ -69,13 +69,13 @@ You can also add files to be displayed or attached to your project overview. ### Project members widget -You can add a widget which displays all project members and their corresponding role(s) for this project at the project overview page. +You can add a widget which displays all project members and their corresponding role for this project at the project overview page. ![project members](image-20191112134827557.png) With the green button you can [add members to your project](/getting-started/invite-members/). -The View all members button brings you to the list of members in the project. +The View all members button brings you to the list of project members. ### News widget @@ -107,7 +107,7 @@ Add your project status as a widget to display at one sight whether your project First, select your project status from the drop-down. You can choose between: -ON TRACK (green +ON TRACK (green) OFF TRACK (red) @@ -137,11 +137,11 @@ The subprojects widget lists all subproject of the respective project on the ove The widget only links the first subproject hierarchy and not the children of a subproject. -To edit to project hierarchy, go to the [project settings](./project-admin-guide/). +To edit the project hierarchy, go to the [project settings](./project-admin-guide/). ### Work package graph widgets (Premium feature) -The work package graph widgets display information about the work packages within a project. They can be displayed in different graph views, such as a bar graph or a pie chart. +The work package graph widgets displays information about the work packages within a project. They can be displayed in different graph views, such as a bar graph or a pie chart. ![work package graph widget](image-20191112150530814.png) @@ -163,7 +163,7 @@ Next, select the **Chart type** how the work package information shall be displa **Filter** the work packages for your chart. -Click on the Filter tab in order to configure the work packages which shall be displayed, e.g. only work package with priority high. +Click on the Filter tab in order to configure the work packages which shall be displayed, e.g. only work packages with high priority. ![filter work package graph widget](image-20191112151535247.png) @@ -205,4 +205,4 @@ To **re-size** a widget, click on the grey icon in the lower right hand corner o To remove a widget from the project overview page, click on the three dots at the top right corner of the widget and select **Remove widget**. -![remove-widget](remove-widget.png) \ No newline at end of file +![remove-widget](remove-widget.png) diff --git a/help/user-guide/roadmap.md b/help/user-guide/roadmap.md index 751af1b43b..3a5213bd0e 100644 --- a/help/user-guide/roadmap.md +++ b/help/user-guide/roadmap.md @@ -1,5 +1,5 @@ --- -nav: +sidebar_navigation: title: Roadmap priority: 880 description: Find out about the Product Roadmap and Release planning in OpenProject