Oliver Günther
5 years ago
commit
08c062c0ff
Binary file not shown.
@ -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) |
||||
|
After Width: | Height: | Size: 104 KiB |
|
After Width: | Height: | Size: 169 KiB |
|
After Width: | Height: | Size: 169 KiB |
|
After Width: | Height: | Size: 157 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 29 KiB |
|
After Width: | Height: | Size: 63 KiB |
|
After Width: | Height: | Size: 375 KiB |
|
After Width: | Height: | Size: 65 KiB |
|
After Width: | Height: | Size: 185 KiB |
|
After Width: | Height: | Size: 120 KiB |
|
After Width: | Height: | Size: 175 KiB |
|
After Width: | Height: | Size: 120 KiB |
|
After Width: | Height: | Size: 24 KiB |
|
After Width: | Height: | Size: 184 KiB |
|
After Width: | Height: | Size: 90 KiB |
|
After Width: | Height: | Size: 355 KiB |
|
After Width: | Height: | Size: 109 KiB |
|
After Width: | Height: | Size: 108 KiB |
|
After Width: | Height: | Size: 1.1 MiB |
|
After Width: | Height: | Size: 2.6 MiB |
|
After Width: | Height: | Size: 4.0 MiB |
|
After Width: | Height: | Size: 938 KiB |
|
After Width: | Height: | Size: 2.0 MiB |
|
After Width: | Height: | Size: 2.0 MiB |
|
After Width: | Height: | Size: 868 KiB |
|
After Width: | Height: | Size: 138 KiB |
|
After Width: | Height: | Size: 97 KiB |
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 86 KiB |
|
After Width: | Height: | Size: 102 KiB |
@ -1,27 +1,17 @@ |
||||
# Installation and Operation Guides |
||||
|
||||
This section concerns the installation, upgrading, backup, and other operation guides for the OpenProject Community and Enterprise editions. |
||||
This section concerns the installation and operation of OpenProject (Community and Enterprise editions). |
||||
|
||||
## Overview |
||||
|
||||
| Main Topics | Description | |
||||
| ----------- | :---------- | |
||||
| [System requirements](system-requirements) | Learn the minimum configuration required to run OpenProject | |
||||
| [Installation](installation/) | How to install OpenProject | |
||||
| [Operation & Maintenance](operation/) | Guides on how to configure, backup, upgrade, and monitor your OpenProject installation | |
||||
| [Advanced configuration](configuration/) | Guides on how to perform advanced configuration of your OpenProject installation | |
||||
| [Other](misc/) | Guides on infrequent operations such as MySQL to PostgreSQL migration | |
||||
|
||||
## Installing OpenProject |
||||
For production environments and when using a [supported distribution](system-requirements), we recommend using the [packaged installation](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. |
||||
|
||||
OpenProject provides three different means of installation on Linux and Unix distributions. |
||||
|
||||
1. [The packaged installation](packaged/installation) |
||||
2. [The docker-based installation](docker/installation) |
||||
3. [The manual installation](docker/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. |
||||
|
||||
|
||||
|
||||
## Upgrading, Backup and Maintenance |
||||
|
||||
For upgrading, backup and migration guides, please select the installation method you have chosen for installing OpenProject on your server: |
||||
|
||||
- [The packaged installation](packaged) |
||||
- [The docker-based installation](docker) |
||||
- [The manual installation](docker) |
||||
A [manual installation](installation/manual) 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. |
||||
|
||||
@ -0,0 +1,17 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Advanced configuration |
||||
priority: 100 |
||||
--- |
||||
|
||||
# Advanced configuration |
||||
|
||||
| ----------- | :---------- | |
||||
| [List of supported environment variables](./env-variables) | TODO: The full list of environment variables you can use to override the default configuration | |
||||
| [Configuring SSL](./ssl) | How to configure SSL so that your OpenProject installation is available over HTTPS | |
||||
| [Configuring outbound emails](./outbound-emails) | How to configure outbound emails for notifications, etc. | |
||||
| [Configuring inbound emails](./inbound-emails) | TODO: How to configure inbound emails for work package updates directly from an email | |
||||
| [Configuring a custom database](./database) | How to use an external database | |
||||
| [Configuring a custom web server](./server) | TODO: How to use a custom web server (e.g. NginX) with your OpenProject installation | |
||||
| [Configuring a custom web server](./cache) | TODO: How to use a custom caching server with your OpenProject installation | |
||||
| [Adding plugins](./plugins) | TODO: How to add plugins to your OpenProject installation | |
||||
@ -0,0 +1,25 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Configuring a custom database server |
||||
priority: 6 |
||||
--- |
||||
|
||||
# Configuring a custom database server |
||||
|
||||
## Package-based installation |
||||
|
||||
Simply run `sudo openproject reconfigure`, and when the database wizard is displayed, select the **Use an existing PostgreSQL database** option and fill in the required details ([cf the initial configuration section](../installation/packaged/#step-1-postgresql-database-configuration)) |
||||
|
||||
## Docker-based installation |
||||
|
||||
You can simply pass a custom `DATABASE_URL` environment variable on the |
||||
docker command-line, which could point to an external database. |
||||
|
||||
Example: |
||||
|
||||
```bash |
||||
docker run -d ... -e DATABASE_URL=mysql2://user:pass@host:port/dbname openproject/community:10 |
||||
``` |
||||
|
||||
The docker image will make sure that the database gets the migrations and demo |
||||
data as well. |
||||
@ -0,0 +1,55 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Configuring outbound emails |
||||
priority: 8 |
||||
--- |
||||
|
||||
# Configuring outbound emails |
||||
|
||||
By default, both the docker and package-based installations will setup a postfix server to allow sending emails from your server. While it is a good starting point, it is not a recommended production setup since you will most likely run into delivery issues since your server will lack the trust of a proper email provider. |
||||
|
||||
In this guide we will describe how to configure outbound emails using an external SMTP server. |
||||
|
||||
## Requirements |
||||
|
||||
You will need to have SMTP settings ready. Those can eiher be from a company |
||||
SMTP server, a GMail account, or a public provider such as |
||||
[SendGrid](https://www.sendgrid.com/). |
||||
|
||||
Taking SendGrid as an example, you would need to sign up on their website (they |
||||
offer a free plan with up to 12000 emails per month), and once your account is |
||||
provisioned, generate a new API key and copy it somewhere (it looks like |
||||
`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`). You |
||||
could also simply use your SendGrid username and password, but this is less |
||||
secure. |
||||
|
||||
You can adjust those settings for other SMTP providers, such as GMail, |
||||
Mandrill, etc. Please refer to the documentation of the corresponding provider |
||||
to see what values should be used. |
||||
|
||||
## Package-based installation (DEB/RPM) |
||||
|
||||
If you installed OpenProject with the package-based installation, simply run `sudo openproject reconfigure`, and when the email wizard is displayed, select the **SMTP** option and fill in the required details ([cf the initial configuration section](../installation/packaged/#step-4-outgoing-email-configuration)) |
||||
|
||||
## Docker installation |
||||
|
||||
If you installed OpenProject with Docker, here is how you would enable outbound |
||||
emails through the use of the SMTP environment variables (with SendGrid, the |
||||
`SMTP_USER_NAME` is always `apikey`. Just replace `SMTP_PASSWORD` with the API |
||||
key you've generated and you should be good to |
||||
go): |
||||
|
||||
```bash |
||||
docker run -d \ |
||||
-e EMAIL_DELIVERY_METHOD=smtp \ |
||||
-e SMTP_ADDRESS=smtp.sendgrid.net \ |
||||
-e SMTP_PORT=587 \ |
||||
-e SMTP_DOMAIN=my.domain.com \ |
||||
-e SMTP_AUTHENTICATION=login \ |
||||
-e SMTP_ENABLE_STARTTLS_AUTO=true \ |
||||
-e SMTP_USER_NAME="apikey" \ |
||||
-e SMTP_PASSWORD="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" \ |
||||
... |
||||
``` |
||||
|
||||
|
||||
@ -0,0 +1,31 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Configuring SSL |
||||
priority: 9 |
||||
--- |
||||
|
||||
# Configuring SSL |
||||
|
||||
## Package-based installation (DEB/RPM) |
||||
|
||||
SSL configuration can be applied on the first installation, or at any time by reconfiguring the application with: |
||||
|
||||
```bash |
||||
sudo openproject reconfigure |
||||
``` |
||||
|
||||
You will be prompted with the same dialogs than on the [initial configuration](initial_configuration) guide. This assumes that you select the **install** option when the **server/autoinstall** dialog appears, and that you have certificate and key files available on your server at a path you know. |
||||
|
||||
[initial_configuration]: ../installation/packaged/#install-apache2-web-server-default |
||||
|
||||
## Docker-based installation |
||||
|
||||
The current Docker image does not support SSL by default. Usually you would |
||||
already have an existing Apache or NginX server on your host, with SSL |
||||
configured, which you could use to set up a simple ProxyPass rule to direct |
||||
traffic to the container. |
||||
|
||||
If you really want to enable SSL from within the container, you could try |
||||
mounting a custom apache2 directory when you launch the container with `-v |
||||
my/apache2/conf:/etc/apache2`. This would entirely replace the configuration |
||||
we're using. |
||||
@ -1,23 +0,0 @@ |
||||
# Backup your OpenProject installation (Docker) |
||||
|
||||
Note: this guide only applies if you've installed OpenProject with our Docker image. |
||||
|
||||
If you've followed the steps described in the installation guide for Docker, |
||||
then you just need to make a backup of the exported volumes, at your |
||||
convenience. As a reminder, here is the recommended way to launch OpenProject |
||||
with Docker: |
||||
|
||||
sudo mkdir -p /var/lib/openproject/{pgdata,logs,static} |
||||
|
||||
docker run -d -p 8080:80 --name openproject -e SECRET_KEY_BASE=secret \ |
||||
-v /var/lib/openproject/pgdata:/var/lib/postgresql/9.6/main \ |
||||
-v /var/lib/openproject/logs:/var/log/supervisor \ |
||||
-v /var/lib/openproject/static:/var/db/openproject \ |
||||
openproject/community:8 |
||||
|
||||
If you're using the same local directories than the above command, then you |
||||
just need to backup your local `/var/lib/openproject` folder (for instance to |
||||
S3 or FTP). |
||||
|
||||
If at any point you want to restore from a backup, just put your backup in |
||||
`/var/lib/openproject` on your local host, and re-launch the docker container. |
||||
@ -1,28 +0,0 @@ |
||||
# Upgrade your OpenProject installation (Docker) |
||||
|
||||
Upgrading a Docker container is easy. First, pull the latest version of the image: |
||||
|
||||
docker pull openproject/community:latest |
||||
|
||||
Then stop and remove your existing container: |
||||
|
||||
docker stop openproject |
||||
docker rm openproject |
||||
|
||||
Finally, re-launch the container in the same way you launched it previously. |
||||
This time, it will use the new image: |
||||
|
||||
docker run -d ... openproject/community:latest |
||||
|
||||
|
||||
# Upgrade Notes |
||||
|
||||
## OpenProject 9.x |
||||
|
||||
### 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. |
||||
@ -0,0 +1,14 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Installation |
||||
priority: 400 |
||||
--- |
||||
|
||||
# Installing OpenProject |
||||
|
||||
OpenProject can be setup in two different ways: |
||||
|
||||
| ----------- | :---------- | |
||||
| [Installation with DEB/RPM packages](./packaged) | This is the recommended way to install OpenProject | |
||||
| [Installation with docker](./docker) | This method of installation will undergo some changes soon and is currently not recommended | |
||||
|
||||
@ -0,0 +1,124 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Docker |
||||
priority: 300 |
||||
--- |
||||
|
||||
# Install OpenProject with Docker |
||||
|
||||
[Docker][docker] is a way to distribute self-contained applications easily. We |
||||
provide a Docker image for the Community Edition that you can very easily |
||||
install and upgrade on your servers. However, contrary to the manual or |
||||
package-based installation, your machine needs to have the Docker Engine |
||||
installed first, which usually requires a recent operating system. Please see |
||||
the [Docker Engine installation page][docker-install] if you don't have Docker |
||||
installed. |
||||
|
||||
Also, please note that the Docker image is quite new and might not support all |
||||
the options that the package-based or manual installation provides. |
||||
|
||||
[docker]: https://www.docker.com/ |
||||
[docker-install]: https://docs.docker.com/install/ |
||||
|
||||
## Quick Start |
||||
|
||||
The fastest way to get an OpenProject instance up and running is to run the |
||||
following command: |
||||
|
||||
```bash |
||||
docker run -it -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:10 |
||||
``` |
||||
|
||||
This will take a bit of time the first time you launch it, but after a few |
||||
minutes you should see a success message indicating the default administration |
||||
password (login: `admin`, password: `admin`). |
||||
|
||||
You can then launch a browser and access your new OpenProject installation at |
||||
<http://localhost:8080>. Easy! |
||||
|
||||
To stop the container, simply hit CTRL-C. |
||||
|
||||
Note that the above command will not daemonize the container and will display |
||||
the logs to your terminal, which helps with debugging if anything goes wrong. |
||||
For normal usage you probably want to start it in the background, which can be |
||||
achieved with the `-d` flag: |
||||
|
||||
```bash |
||||
docker run -d -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:10 |
||||
``` |
||||
|
||||
## Recommended usage |
||||
|
||||
The one-liner above is great to get started quickly, but if you want to run |
||||
OpenProject in production you will likely want to ensure that your data is not |
||||
lost if you restart the container. |
||||
|
||||
To achieve this, we recommend that you create a directory on your host system |
||||
where the Docker Engine is installed (for instance: `/var/lib/openproject`) |
||||
where all this data will be stored. |
||||
|
||||
You can use the following commands to create the local directories where the |
||||
data will be stored across container restarts, and start the container with |
||||
those directories mounted: |
||||
|
||||
```bash |
||||
sudo mkdir -p /var/lib/openproject/{pgdata,static} |
||||
|
||||
docker run -d -p 8080:80 --name openproject -e SECRET_KEY_BASE=secret \ |
||||
-v /var/lib/openproject/pgdata:/var/openproject/pgdata \ |
||||
-v /var/lib/openproject/static:/var/openproject/assets \ |
||||
openproject/community:10 |
||||
``` |
||||
|
||||
Since we named the container, you can now stop it by running: |
||||
|
||||
```bash |
||||
docker stop openproject |
||||
``` |
||||
|
||||
And start it again: |
||||
|
||||
```bash |
||||
docker start openproject |
||||
``` |
||||
|
||||
If you want to destroy the container, run the following commands |
||||
|
||||
```bash |
||||
docker stop openproject |
||||
docker rm openproject |
||||
``` |
||||
|
||||
## Initial configuration |
||||
|
||||
OpenProject is usually configured through a YAML file, but with the Docker |
||||
image you need to pass all configuration through environment variables. You can |
||||
overwrite any of the values usually found in the standard YAML file by using |
||||
[environment variables](list_of_env_variables). |
||||
|
||||
Environment variables can be either passed directly on the command-line to the |
||||
Docker Engine, or via an environment file: |
||||
|
||||
```bash |
||||
docker run -d -e KEY1=VALUE1 -e KEY2=VALUE2 ... |
||||
# or |
||||
docker run -d --env-file path/to/file ... |
||||
``` |
||||
|
||||
For more advanced configuration, please have a look at the [Advanced configuration](advanced_configuration) section. |
||||
|
||||
[list_of_env_variables]: ../configuration/env-variables |
||||
[advanced_configuration]: ../configuration |
||||
|
||||
## Launching a specific process instead of the all-in-one installation |
||||
|
||||
OpenProject is made of multiple processes (web, worker, cron, etc.). By default the docker image will launch all those processes within a single container for ease of use. However some use cases might require that you only launch one process per container, in which case you should override the docker command to specify the process you want to launch. |
||||
|
||||
By default the container will run `./docker/supervisord`, but you can override this with `./docker/web`, `./docker/worker`, `./docker/cron` to launch the individual services separately (e.g. in a docker-compose file). Please note that in this configuration you will have to setup the external services (postgres, memcached, email sending) by yourself. |
||||
|
||||
Example: |
||||
|
||||
```bash |
||||
docker run -d -e DATABASE_URL=xxx ... openproject/community:10 ./docker/web |
||||
docker run -d -e DATABASE_URL=xxx ... openproject/community:10 ./docker/worker |
||||
``` |
||||
@ -0,0 +1,461 @@ |
||||
--- |
||||
sidebar_navigation: false |
||||
--- |
||||
|
||||
# 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.** |
||||
|
||||
Please be aware that: |
||||
|
||||
* This guide requires that you have a clean Ubuntu 18.04 **x64** installation |
||||
with administrative rights (i.e. you must be able to `sudo`). We have tested |
||||
the installation guide on an Ubuntu Server image, but it should work on any |
||||
derivative. You may need to alter some of the commands to match your |
||||
derivative. |
||||
|
||||
* OpenProject will be installed with a PostgreSQL database. |
||||
|
||||
* OpenProject will be served in a production environment with the Apache server |
||||
(this guide should work similarly with other servers, like nginx and others) |
||||
|
||||
Note: We have highlighted commands to execute like this |
||||
|
||||
```bash |
||||
[user@host] command to execute |
||||
``` |
||||
|
||||
The `user` is the operating system user the command is executed with. |
||||
In our case it will be `root` for most of the time or `openproject`. |
||||
|
||||
If you find any bugs or you have any recommendations for improving this |
||||
tutorial, please, feel free to create a pull request against this guide. |
||||
|
||||
## Create a dedicated OpenProject user |
||||
|
||||
```bash |
||||
sudo groupadd openproject |
||||
sudo useradd --create-home --gid openproject openproject |
||||
sudo passwd openproject #(enter desired password) |
||||
``` |
||||
|
||||
## Install the required system dependencies |
||||
|
||||
```bash |
||||
[root@host] apt-get update -y |
||||
[root@host] apt-get install -y zlib1g-dev build-essential \ |
||||
libssl-dev libreadline-dev \ |
||||
libyaml-dev libgdbm-dev \ |
||||
libncurses5-dev automake \ |
||||
libtool bison libffi-dev git curl \ |
||||
poppler-utils unrtf tesseract-ocr catdoc \ |
||||
libxml2 libxml2-dev libxslt1-dev # nokogiri |
||||
``` |
||||
|
||||
## Install the caching server (memcached) |
||||
|
||||
```bash |
||||
[root@host] apt-get install -y memcached |
||||
``` |
||||
|
||||
## Install and setup the database server (PostgreSQL) |
||||
|
||||
OpenProject requires PostgreSQL v9.5+. If you system package is too old, you can check https://www.postgresql.org/download/ to get a newer version installed. In our case, Ubuntu 18.04 comes with a recent-enough version so we can use the system packages: |
||||
|
||||
```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 database user for OpenProject. This will prompt you for a password. We are going to assume in the following guide that this password is '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, revert to the previous system user: |
||||
|
||||
```bash |
||||
[postgres@host] exit |
||||
# You will be root again now. |
||||
``` |
||||
|
||||
## Installation of Ruby |
||||
|
||||
The are several possibilities to install Ruby on your machine. We will |
||||
use [rbenv](http://rbenv.org/). Please be aware that the actual installation of a specific Ruby version takes some |
||||
time to finish. |
||||
|
||||
```bash |
||||
[root@host] su openproject --login |
||||
[openproject@host] git clone https://github.com/sstephenson/rbenv.git ~/.rbenv |
||||
[openproject@host] echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.profile |
||||
[openproject@host] echo 'eval "$(rbenv init -)"' >> ~/.profile |
||||
[openproject@host] source ~/.profile |
||||
[openproject@host] git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build |
||||
|
||||
[openproject@host] rbenv install 2.6.1 |
||||
[openproject@host] rbenv rehash |
||||
[openproject@host] rbenv global 2.6.1 |
||||
``` |
||||
|
||||
To check our Ruby installation we run `ruby --version`. It should output |
||||
something very similar to: |
||||
|
||||
``` |
||||
ruby 2.6.1pXYZ (....) [x86_64-linux] |
||||
``` |
||||
|
||||
## Installation of Node |
||||
|
||||
The are several possibilities to install Node on your machine. We will |
||||
use [nodenv](https://github.com/OiNutter/nodenv#installation). Please |
||||
run `su openproject --login` if you are the `root` user. If you are |
||||
already the `openproject` user you can skip this command. Please be |
||||
aware that the actual installation of a specific node version takes some |
||||
time to finish. |
||||
|
||||
```bash |
||||
[openproject@host] git clone https://github.com/OiNutter/nodenv.git ~/.nodenv |
||||
[openproject@host] echo 'export PATH="$HOME/.nodenv/bin:$PATH"' >> ~/.profile |
||||
[openproject@host] echo 'eval "$(nodenv init -)"' >> ~/.profile |
||||
[openproject@host] source ~/.profile |
||||
[openproject@host] git clone git://github.com/OiNutter/node-build.git ~/.nodenv/plugins/node-build |
||||
|
||||
[openproject@host] nodenv install 8.12.0 |
||||
[openproject@host] nodenv rehash |
||||
[openproject@host] nodenv global 8.12.0 |
||||
``` |
||||
|
||||
To check our Node installation we run `node --version`. It should output something very similar to: |
||||
|
||||
``` |
||||
v8.12.0 |
||||
``` |
||||
|
||||
## Installation of OpenProject |
||||
|
||||
We will install the OpenProject Community Edition. It contains the recommended set of plugins for use |
||||
with OpenProject. For more information, see https://github.com/opf/openproject. |
||||
|
||||
|
||||
```bash |
||||
[openproject@host] cd ~ |
||||
[openproject@host] git clone https://github.com/opf/openproject.git --branch stable/9 --depth 1 |
||||
[openproject@host] cd openproject |
||||
# Ensure rubygems is up-to-date for bundler 2 |
||||
[openproject@host] gem update --system |
||||
[openproject@host] gem install bundler |
||||
# Replace mysql with postgresql if you had to install MySQL |
||||
[openproject@host] bundle install --deployment --without mysql2 sqlite development test therubyracer docker |
||||
[openproject@host] npm install |
||||
``` |
||||
|
||||
## Configure OpenProject |
||||
|
||||
Create and configure the database configuration file in config/database.yml |
||||
(relative to the openproject directory). |
||||
|
||||
```bash |
||||
[openproject@host] cp config/database.yml.example config/database.yml |
||||
``` |
||||
|
||||
Now we edit the `config/database.yml` file and insert our database credentials for PostgreSQL. |
||||
It should look like this (please keep in mind that you have to use the values |
||||
you used above: user, database and password): |
||||
|
||||
```yaml |
||||
production: |
||||
adapter: postgresql |
||||
encoding: unicode |
||||
database: openproject |
||||
pool: 5 |
||||
username: openproject |
||||
password: openproject |
||||
``` |
||||
|
||||
Next we configure email notifications (this example uses a gmail account) by creating the `configuration.yml` in config directory. |
||||
|
||||
```bash |
||||
[openproject@host] cp config/configuration.yml.example config/configuration.yml |
||||
``` |
||||
|
||||
Now we edit the `configuration.yml` file to suit our needs. |
||||
|
||||
```yaml |
||||
production: #main level |
||||
email_delivery_method: :smtp #settings for the production environment |
||||
smtp_address: smtp.gmail.com |
||||
smtp_port: 587 |
||||
smtp_domain: smtp.gmail.com |
||||
smtp_user_name: ***@gmail.com |
||||
smtp_password: **** |
||||
smtp_enable_starttls_auto: true |
||||
smtp_authentication: plain |
||||
``` |
||||
|
||||
Add this line into `configuration.yml` file at the end of the file for |
||||
a better performance of OpenProject: |
||||
|
||||
```yaml |
||||
rails_cache_store: :memcache |
||||
``` |
||||
|
||||
__NOTE:__ You should validate your `yml` files, for example with |
||||
http://www.yamllint.com/. Both, the `database.yml` and `configuration.yml` |
||||
file are sensitive to whitespace. It is pretty easy to write |
||||
invalid `yml` files without seeing the error. Validating those files |
||||
prevents you from such errors. |
||||
|
||||
|
||||
## Finish the installation of OpenProject |
||||
|
||||
```bash |
||||
[openproject@host] cd ~/openproject |
||||
[openproject@host] RAILS_ENV="production" ./bin/rake db:create |
||||
[openproject@host] RAILS_ENV="production" ./bin/rake db:migrate |
||||
[openproject@host] RAILS_ENV="production" ./bin/rake db:seed |
||||
[openproject@host] RAILS_ENV="production" ./bin/rake assets:precompile |
||||
``` |
||||
|
||||
**NOTE:** When not specified differently, the default data loaded via db:seed will have an english localization. You can choose to seed in a different language by specifying the language via the `LOCALE` environment variable on the call to `db:seed`. E.g. |
||||
```bash |
||||
[openproject@all] RAILS_ENV="production" LOCALE=fr ./bin/rake db:seed |
||||
``` |
||||
will seed the database in the french language. |
||||
|
||||
### Secret token |
||||
|
||||
You need to generate a secret key base for the production environment with `./bin/rake secret` and make that available through the environment variable `SECRET_KEY_BASE`. |
||||
In this installation guide, we will use the local `.profile` of the OpenProject user. You may alternatively set the environment variable in `/etc/environment` or pass it to the server upon start manually in `/etc/apache2/envvars`. |
||||
|
||||
```bash |
||||
[openproject@host] echo "export SECRET_KEY_BASE=$(./bin/rake secret)" >> ~/.profile |
||||
[openproject@host] source ~/.profile |
||||
``` |
||||
|
||||
## Serve OpenProject with Apache and Passenger |
||||
|
||||
First, we exit the current bash session with the openproject user, |
||||
so that we are again in a root shell. |
||||
|
||||
```bash |
||||
[openproject@ubuntu] exit |
||||
``` |
||||
|
||||
Then, we prepare apache and passenger: |
||||
|
||||
```bash |
||||
[root@host] apt-get install -y apache2 libcurl4-gnutls-dev \ |
||||
apache2-dev libapr1-dev \ |
||||
libaprutil1-dev |
||||
[root@ubuntu] chmod o+x "/home/openproject" |
||||
``` |
||||
|
||||
Now, the Passenger gem is installed and integrated into apache. |
||||
|
||||
```bash |
||||
[root@ubuntu] su openproject --login |
||||
[openproject@ubuntu] cd ~/openproject |
||||
[openproject@ubuntu] gem install passenger |
||||
[openproject@ubuntu] passenger-install-apache2-module |
||||
``` |
||||
|
||||
If you are running on a Virtual Private Server, you need to make sure you have atleast 1024mb of RAM before running the `passenger-install-apache2-module`. |
||||
|
||||
Follow the instructions passenger provides. |
||||
The passenger installer will ask you the question in "Which languages are you |
||||
interested in?". We are interested only in ruby. |
||||
|
||||
The passenger installer tells us to edit the apache config files. |
||||
To do this, continue as the root user: |
||||
|
||||
```bash |
||||
[openproject@host] exit |
||||
``` |
||||
|
||||
As told by the installer, create the file /etc/apache2/mods-available/passenger.load and add the following line. |
||||
But before copy&pasting the following lines, check if the content (especially the version numbers!) is the same as the passenger-install-apache2-module installer said. When you're in doubt, do what passenger tells you. |
||||
|
||||
|
||||
```apache |
||||
LoadModule passenger_module /home/openproject/.rbenv/versions/2.1.6/lib/ruby/gems/2.1.0/gems/passenger-5.0.14/buildout/apache2/mod_passenger.so |
||||
``` |
||||
|
||||
Then create the file /etc/apache2/mods-available/passenger.conf with the following contents (again, take care of the version numbers!): |
||||
|
||||
```apache |
||||
<IfModule mod_passenger.c> |
||||
PassengerRoot /home/openproject/.rbenv/versions/2.1.6/lib/ruby/gems/2.1.0/gems/passenger-5.0.14 |
||||
PassengerDefaultRuby /home/openproject/.rbenv/versions/2.1.6/bin/ruby |
||||
</IfModule> |
||||
``` |
||||
|
||||
Then run: |
||||
|
||||
```bash |
||||
[root@openproject] a2enmod passenger |
||||
``` |
||||
|
||||
As the root user, create the file /etc/apache2/sites-available/openproject.conf with the following contents: |
||||
|
||||
```apache |
||||
SetEnv EXECJS_RUNTIME Disabled |
||||
|
||||
<VirtualHost *:80> |
||||
ServerName yourdomain.com |
||||
# !!! Be sure to point DocumentRoot to 'public'! |
||||
DocumentRoot /home/openproject/openproject/public |
||||
<Directory /home/openproject/openproject/public> |
||||
# This relaxes Apache security settings. |
||||
AllowOverride all |
||||
# MultiViews must be turned off. |
||||
Options -MultiViews |
||||
# Uncomment this if you're on Apache >= 2.4: |
||||
Require all granted |
||||
</Directory> |
||||
|
||||
# Request browser to cache assets |
||||
<Location /assets/> |
||||
ExpiresActive On ExpiresDefault "access plus 1 year" |
||||
</Location> |
||||
|
||||
</VirtualHost> |
||||
``` |
||||
|
||||
Let's enable our new openproject site (and disable the default site, if necessary) |
||||
|
||||
```bash |
||||
[root@host] a2dissite 000-default |
||||
[root@host] a2ensite openproject |
||||
``` |
||||
|
||||
Now, we (re-)start Apache: |
||||
|
||||
```bash |
||||
[root@host] service apache2 restart |
||||
``` |
||||
|
||||
Your OpenProject installation should be accessible on port 80 (http). A default admin-account is created for you having the following credentials: |
||||
|
||||
Username: `admin` |
||||
Password: `admin` |
||||
|
||||
Please, change the password on the first login. Also, we highly recommend to configure the SSL module in Apache for https communication. |
||||
|
||||
## Activate background jobs |
||||
|
||||
OpenProject sends (some) mails asynchronously by using background jobs. All such jobs are collected in a queue, so that a separate process can work on them. This means that we have to start the background worker. To automate this, we put the background worker into a cronjob. |
||||
|
||||
```bash |
||||
[root@all] su - openproject -c "bash -l" |
||||
[openproject@all] crontab -e |
||||
``` |
||||
|
||||
Now, the crontab file opens in the standard editor. Add the following entry to the file: |
||||
|
||||
```cron |
||||
*/1 * * * * cd /home/openproject/openproject; /home/openproject/.rvm/gems/ruby-2.1.5/wrappers/rake jobs:workoff |
||||
``` |
||||
|
||||
This will start the worker job every minute. |
||||
|
||||
## Follow-Ups |
||||
|
||||
Your OpenProject installation is ready to run. Please refer to the [Operation guides](../../operation) or the [Advanced configuration guides](../../advanced-configuration) for more details on how to operate and configure OpenProject. |
||||
|
||||
## Plug-In installation (Optional) |
||||
|
||||
This step is optional. |
||||
|
||||
OpenProject can be extended by various plug-ins, which extend OpenProject's capabilities. |
||||
For general information and a list of all plug-ins known to us, refer to to the [plug-in page](https://community.openproject.org/projects/openproject/wiki/OpenProject_Plug-Ins). |
||||
|
||||
OpenProject plug-ins are separated in ruby gems. You can install them by listing them in a file called `Gemfile.plugins`. An example `Gemfile.plugins` file looks like this: |
||||
|
||||
```ruby |
||||
# Required by backlogs |
||||
gem "openproject-meeting", git: "https://github.com/finnlabs/openproject-meeting.git", :tag => "v4.2.2" |
||||
``` |
||||
|
||||
If you have modified the `Gemfile.plugin` file, always repeat the following steps of the OpenProject installation: |
||||
|
||||
```bash |
||||
[openproject@all] cd ~/openproject |
||||
[openproject@all] bundle install |
||||
[openproject@all] npm install |
||||
[openproject@all] RAILS_ENV="production" ./bin/rake db:migrate |
||||
[openproject@all] RAILS_ENV="production" ./bin/rake db:seed |
||||
[openproject@all] RAILS_ENV="production" ./bin/rake assets:precompile |
||||
``` |
||||
|
||||
Restart the OpenProject server afterwards: |
||||
|
||||
```bash |
||||
[openproject@all] touch ~/openproject/tmp/restart.txt |
||||
``` |
||||
|
||||
The next web-request to the server will take longer (as the application is restarted). All subsequent request should be as fast as always. |
||||
|
||||
We encourage you to extend OpenProject yourself by writing a plug-in. Please, read the [plugin-contributions](https://community.openproject.org/projects/openproject/wiki/Developing_Plugins) guide for more information. |
||||
|
||||
## Troubleshooting |
||||
|
||||
You can find the error logs for apache here: |
||||
<pre>/var/log/apache2/error.log</pre> |
||||
|
||||
The OpenProject logfile can be found here: |
||||
<pre>/home/openproject/openproject/log/production.log</pre> |
||||
|
||||
If an error occurs, it should be logged there. |
||||
|
||||
If you need to restart the server (for example after a configuration change), do |
||||
|
||||
```bash |
||||
[openproject@all] touch ~/openproject/tmp/restart.txt |
||||
``` |
||||
|
||||
## Frequently asked questions (FAQ) |
||||
|
||||
* **I followed the installation guide faithfully and OpenProject is running. Now, how do I log in?** |
||||
|
||||
The `db:seed` command listed above creates a default admin-user. The username is `admin` and the default password is `admin`. You are forced to change the admin password on the first login. |
||||
If you cannot login as the admin user, make sure that you have executed the `db:seed` command. |
||||
|
||||
```bash |
||||
[openproject@all] RAILS_ENV="production" ./bin/rake db:seed |
||||
``` |
||||
|
||||
* **When accessing OpenProject, I get an error page. How do I find out what went wrong?** |
||||
|
||||
Things can go wrong on different levels. You can find the apache error logs here: |
||||
<pre>/var/log/apache2/error.log</pre> |
||||
The OpenProject log can be found here: |
||||
<pre>/home/openproject/openproject/log/production.log</pre> |
||||
|
||||
* **I cannot solve an error, not even with the log files. How do I get help?** |
||||
|
||||
You can find help in [the OpenProject forums](https://community.openproject.org/projects/openproject/boards). Please tell us, if possible, what you have done (e.g. which guide you have used to install OpenProject), how to reproduce the error, and provide the appropriate error logs. |
||||
It often helps to have a look at the already answered questions, or to search the Internet for the error. Most likely someone else has already solved the same problem. |
||||
|
||||
* **I get errors, since I have installed an OpenProject plug-in** |
||||
|
||||
With each new OpenProject core version, the plug-ins might need to be updated. Please make sure that the plug-in versions of all you plug-ins works with the OpenProject version you use. |
||||
Many plug-ins follow the OpenProject version with their version number (So, if you have installed OpenProject version 4.1.0, the plug-in should also have the version 4.1.0). |
||||
|
||||
## Questions, comments, and feedback |
||||
|
||||
If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the appropriate community [forum](https://community.openproject.org/projects/openproject/boards/9). |
||||
[Follow OpenProject on twitter](https://twitter.com/openproject), and follow the news on [openproject.org](http://openproject.org) to stay up to date. |
||||
|
||||
@ -0,0 +1,339 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Packages |
||||
priority: 400 |
||||
--- |
||||
|
||||
# Install OpenProject with DEB/RPM packages |
||||
|
||||
The packaged installation of OpenProject is the recommended way to install and maintain OpenProject using DEB or RPM packages. |
||||
|
||||
The package will: |
||||
|
||||
- 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 (recommended) |
||||
|
||||
- setup SSL/TLS encryption for the Apache server (optional) |
||||
|
||||
- configure repositories (Git/SVN) (optional) |
||||
|
||||
- configure email settings |
||||
|
||||
The package is available for the following Linux distributions: |
||||
|
||||
| Distribution (**64 bits only**) | |
||||
| ------------------------------- | |
||||
| CentOS/RHEL 7.x | |
||||
| Debian 9 Stretch | |
||||
| Debian 10 Stretch | |
||||
| Suse Linux Enterprise Server 12 | |
||||
| Ubuntu 16.04 Xenial Xerus | |
||||
| Ubuntu 18.04 Bionic Beaver | |
||||
|
||||
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`: |
||||
|
||||
```bash |
||||
$ uname -i |
||||
x86_64 |
||||
``` |
||||
|
||||
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. |
||||
|
||||
## Ubuntu 18.04 |
||||
|
||||
Import the PGP key used to sign our packages: |
||||
|
||||
```bash |
||||
wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - |
||||
``` |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
sudo wget -O /etc/apt/sources.list.d/openproject.list \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/18.04.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
## Ubuntu 16.04 |
||||
|
||||
Import the PGP key used to sign our packages: |
||||
|
||||
```bash |
||||
wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - |
||||
``` |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
sudo wget -O /etc/apt/sources.list.d/openproject.list \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/ubuntu/16.04.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
## Debian 10 |
||||
|
||||
Import the PGP key used to sign our packages: |
||||
|
||||
```bash |
||||
wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - |
||||
``` |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
sudo wget -O /etc/apt/sources.list.d/openproject.list \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/10.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
## Debian 9 |
||||
|
||||
Import the PGP key used to sign our packages: |
||||
|
||||
```bash |
||||
wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add - |
||||
``` |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
sudo wget -O /etc/apt/sources.list.d/openproject.list \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/debian/9.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
## CentOS 7 / RHEL 7 |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
sudo wget -O /etc/yum.repos.d/openproject.repo \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/el/7.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo yum install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
## SLES 12 |
||||
|
||||
Add the OpenProject package source: |
||||
|
||||
```bash |
||||
wget -O /etc/zypp/repos.d/openproject.repo \ |
||||
https://dl.packager.io/srv/opf/openproject/stable/10/installer/sles/12.repo |
||||
``` |
||||
|
||||
Download the OpenProject package: |
||||
|
||||
```bash |
||||
sudo zypper install openproject |
||||
``` |
||||
|
||||
Then finish the installation by reading the [*Initial configuration*][initial-config] section. |
||||
|
||||
[initial-config]: #initial-configuration |
||||
|
||||
# Initial Configuration |
||||
|
||||
After you have successfully installed the OpenProject package, 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: |
||||
|
||||
```bash |
||||
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: |
||||
|
||||
 |
||||
|
||||
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. |
||||
|
||||
```bash |
||||
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. |
||||
|
||||
 |
||||
|
||||
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. |
||||
|
||||
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. |
||||
|
||||
 |
||||
|
||||
**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`. |
||||
|
||||
 |
||||
|
||||
**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) |
||||
|
||||
 |
||||
|
||||
|
||||
### **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. |
||||
|
||||
## 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/) |
||||
|
||||
 |
||||
|
||||
## 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. |
||||
|
||||
 |
||||
|
||||
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. |
||||
|
||||
 |
||||
|
||||
## 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. |
||||
|
||||
 |
||||
|
||||
## 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://<openproject.example.com>/<server prefix>`. |
||||
|
||||
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. |
||||
|
After Width: | Height: | Size: 114 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 30 KiB |
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 17 KiB |
@ -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-<DATE>.sql` (for MySQL) or `OPENPROJECT_DIRECTORY/backup/openproject-production-db-<DATE>.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. |
||||
@ -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 <https://www.postgresql.org/download/> 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:<PASSWORD>@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 |
||||
``` |
||||
|
||||
@ -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 `<OpenProject root>/frontend/bower_components` and `<OpenProject root>/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 |
||||
<IfModule mod_passenger.c> |
||||
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 |
||||
</IfModule> |
||||
``` |
||||
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 #<String ..>` 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/). |
||||
@ -0,0 +1,12 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Other |
||||
priority: 0 |
||||
--- |
||||
|
||||
# Guides for infrequent operations |
||||
|
||||
| ----------- | |
||||
| [Migrating packaged-based installation from MySQL to PostgreSQL](./packaged-postgresql-migration) | |
||||
| [Migrating docker-based installation from MySQL to PostgreSQL](./docker-postgresql-migration) | |
||||
| [Migrating your OpenProject installation to another server](./migration) | |
||||
@ -1,5 +1,7 @@ |
||||
# Migrating your Docker OpenProject database to PostgreSQL |
||||
|
||||
TODO: review |
||||
|
||||
This guide will migrate your docker-based MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). |
||||
|
||||
## Backing up |
||||
@ -1,5 +1,7 @@ |
||||
# Migrating your packaged OpenProject installation to another environment |
||||
|
||||
TODO: review |
||||
|
||||
**Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages. |
||||
|
||||
Migrating your OpenProject packaged installation to another host or environment is trivial and may be combined with, e.g., minor or major package upgrades due to our migration system. |
||||
@ -1,5 +1,7 @@ |
||||
# Migrating your packaged OpenProject database to PostgreSQL |
||||
|
||||
TODO: review |
||||
|
||||
**Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages. |
||||
|
||||
This guide will migrate your packaged MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). |
||||
@ -0,0 +1,21 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Operation |
||||
priority: 200 |
||||
--- |
||||
|
||||
# Operating OpenProject |
||||
|
||||
| ----------- | :---------- | |
||||
| [(Re)Configuring](./reconfiguring) | How to (re)configure your OpenProject installation | |
||||
| [Backing up](./backing-up) | How to backup your OpenProject data | |
||||
| [Restoring](./restoring) | How to restore from a backup | |
||||
| [Upgrading](./upgrading) | How to upgrade your OpenProject installation | |
||||
| [Monitoring & Logs](./monitoring) | How to monitor your OpenProject installation (logs, health checks) | |
||||
| [Process control](./control) | How to start/stop/restart, execute processes in your OpenProject installation | |
||||
| [FAQ](./faq) | Frequently asked questions | |
||||
|
||||
<!-- |
||||
| [Troubleshooting](./troubleshooting) | How to troubleshoot your OpenProject installation | |
||||
| [Scaling up/down](./scaling) | How to scale your OpenProject installation | |
||||
--> |
||||
@ -0,0 +1,74 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Backing up |
||||
priority: 9 |
||||
--- |
||||
|
||||
# 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 (subversion, git) if applicable |
||||
|
||||
## Package-based installation (DEB/RPM) |
||||
|
||||
The DEB/RPM packages provide a backup tool which can be used to take a snapshot |
||||
of the current OpenProject installation. This tool will create a backup of |
||||
all parts mentioned above. The backup tool is invoked by executing the following |
||||
command: |
||||
|
||||
```bash |
||||
sudo openproject run backup |
||||
``` |
||||
|
||||
The command will create backup files in the following location on your system: |
||||
|
||||
```bash |
||||
/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-<date>.sql.gz` or a `postgresql-dump-<date>.pgdump` file). |
||||
|
||||
```bash |
||||
root@ip-10-0-0-228:/home/admin# ls -al /var/db/openproject/backup/ |
||||
total 1680 |
||||
drwxr-xr-x 2 openproject openproject 4096 Nov 19 21:00 . |
||||
drwxr-xr-x 6 openproject openproject 4096 Nov 19 21:00 .. |
||||
-rw-r----- 1 openproject openproject 1361994 Nov 19 21:00 attachments-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 1060 Nov 19 21:00 conf-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 126 Nov 19 21:00 git-repositories-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 332170 Nov 19 21:00 postgresql-dump-20191119210038.pgdump |
||||
-rw-r----- 1 openproject openproject 112 Nov 19 21:00 svn-repositories-20191119210038.tar.gz |
||||
``` |
||||
|
||||
You should then copy those dump files to a secure location, for instance an S3 bucket or some sort of backup server. |
||||
|
||||
## Docker-based installation |
||||
|
||||
TODO: review |
||||
|
||||
If you've followed the steps described in the [installation guide for Docker](../installation/docker), |
||||
then you just need to make a backup of the exported volumes, at your |
||||
convenience. As a reminder, here is the recommended way to launch OpenProject |
||||
with Docker: |
||||
|
||||
```bash |
||||
sudo mkdir -p /var/lib/openproject/{pgdata,logs,static} |
||||
|
||||
docker run -d -p 8080:80 --name openproject -e SECRET_KEY_BASE=secret \ |
||||
-v /var/lib/openproject/pgdata:/var/lib/postgresql/9.6/main \ |
||||
-v /var/lib/openproject/logs:/var/log/supervisor \ |
||||
-v /var/lib/openproject/static:/var/db/openproject \ |
||||
openproject/community:10 |
||||
``` |
||||
|
||||
If you're using the same local directories than the above command, then you |
||||
just need to backup your local `/var/lib/openproject` folder (for instance to |
||||
S3 or FTP). |
||||
@ -0,0 +1,65 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Process control |
||||
priority: 5 |
||||
--- |
||||
|
||||
# Process control for your OpenProject installation |
||||
|
||||
Note: this guide is specific to the package-based installation. |
||||
|
||||
## Restart all the OpenProject processes |
||||
|
||||
```bash |
||||
sudo openproject restart |
||||
``` |
||||
|
||||
## Run commands like rake tasks or rails console |
||||
|
||||
The OpenProject command line tool supports running rake tasks and known scripts. For instance: |
||||
|
||||
Get the current version of OpenProject |
||||
|
||||
```bash |
||||
sudo openproject run bundle exec rake version |
||||
``` |
||||
|
||||
Launch an interactive console to directly interact with the underlying Ruby on Rails application: |
||||
|
||||
```bash |
||||
sudo openproject run console |
||||
``` |
||||
|
||||
Manually launch the database migrations: |
||||
|
||||
```bash |
||||
sudo openproject run rake db:migrate |
||||
``` |
||||
|
||||
Check the version of Ruby used by OpenProject: |
||||
|
||||
```bash |
||||
sudo openproject run ruby -v |
||||
``` |
||||
|
||||
## Scaling the number of web workers |
||||
|
||||
TODO: review |
||||
|
||||
Note: Depending on your free RAM on your system, we recommend you raise the default number of web processes. The default from 9.0.3 onwards is 4 web processes. Each worker will take roughly 300-400MB RAM. |
||||
|
||||
We recommend at least 4 web processes. Please check your current web processes count with: |
||||
|
||||
```bash |
||||
sudo openproject config:get OPENPROJECT_WEB_WORKERS |
||||
``` |
||||
|
||||
If it returns nothing, the default process count of `4` applies. To increase or decrease the process 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. |
||||
@ -0,0 +1,128 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: FAQ |
||||
priority: 4 |
||||
--- |
||||
|
||||
|
||||
# Frequently asked questions - FAQ |
||||
|
||||
TODO: review |
||||
|
||||
## 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. |
||||
@ -0,0 +1,23 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Monitoring & Logs |
||||
priority: 6 |
||||
--- |
||||
|
||||
# Monitoring your OpenProject installation |
||||
|
||||
## Show logs |
||||
|
||||
In a package-based installation, the `openproject` command line tool can 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: |
||||
|
||||
```bash |
||||
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/`. |
||||
@ -0,0 +1,33 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: (Re)configuring |
||||
priority: 10 |
||||
--- |
||||
|
||||
# (Re)configuring OpenProject |
||||
|
||||
## Packaged installation |
||||
|
||||
For packaged installations, you can restart the configuration process by issuing the following command on the server where OpenProject runs: |
||||
|
||||
```bash |
||||
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 option doesn't need to be modified, just hit `ENTER` to proceed to the next screen. |
||||
|
||||
The wizard configuration is stored in `/etc/openproject/installer.dat`. |
||||
|
||||
The wizard will automatically set environment variables to be used by OpenProject. Those variables can be manipulated with the CLI tool that ships with OpenProject: |
||||
|
||||
* `sudo openproject config` will display the list of environment variables set. |
||||
* `sudo openproject config:get KEY` allows you to get the value of single environment variable. |
||||
* `sudo openproject config:set KEY VALUE` allows you to set a new value for a single environment variable. |
||||
|
||||
## Docker installation |
||||
|
||||
For docker-based installations, you should update the environment file passed to the `--env-file` docker option, and issue the following command: |
||||
|
||||
```bash |
||||
docker restart openproject |
||||
``` |
||||
@ -0,0 +1,112 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Restoring |
||||
priority: 8 |
||||
--- |
||||
|
||||
# Restoring an OpenProject backup |
||||
|
||||
## Package-based 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`: |
||||
|
||||
```bash |
||||
root@ip-10-0-0-228:/home/admin# ls -al /var/db/openproject/backup/ |
||||
total 1680 |
||||
drwxr-xr-x 2 openproject openproject 4096 Nov 19 21:00 . |
||||
drwxr-xr-x 6 openproject openproject 4096 Nov 19 21:00 .. |
||||
-rw-r----- 1 openproject openproject 1361994 Nov 19 21:00 attachments-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 1060 Nov 19 21:00 conf-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 126 Nov 19 21:00 git-repositories-20191119210038.tar.gz |
||||
-rw-r----- 1 openproject openproject 332170 Nov 19 21:00 postgresql-dump-20191119210038.pgdump |
||||
-rw-r----- 1 openproject openproject 112 Nov 19 21:00 svn-repositories-20191119210038.tar.gz |
||||
``` |
||||
|
||||
### Stop the processes |
||||
|
||||
First, it is a good idea to stop the OpenProject instance: |
||||
|
||||
```bash |
||||
sudo service openproject stop |
||||
``` |
||||
|
||||
### Restoring assets |
||||
|
||||
Go into the backup directory: |
||||
|
||||
```bash |
||||
cd /var/db/openproject/backup |
||||
``` |
||||
|
||||
Untar the attachments to their destination: |
||||
|
||||
```bash |
||||
tar xzf attachments-20191119210038.tar.gz -C /var/db/openproject/files |
||||
``` |
||||
|
||||
Untar the configuration files to their destination: |
||||
|
||||
```bash |
||||
tar xzf conf-20191119210038.tar.gz -C /etc/openproject/conf.d/ |
||||
``` |
||||
|
||||
Untar the repositories to their destination: |
||||
|
||||
```bash |
||||
tar xzf git-repositories-20191119210038.tar.gz -C /var/db/openproject/git |
||||
tar xzf svn-repositories-20191119210038.tar.gz -C /var/db/openproject/svn |
||||
``` |
||||
|
||||
### Restoring the database |
||||
|
||||
Note: in this section, the `<dbusername>`, `<dbhost>` and `<dbname>` 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: |
||||
|
||||
```bash |
||||
openproject config:get DATABASE_URL |
||||
#=> e.g.: postgres://<dbusername>:<dbpassword>@<dbhost>:<dbport>/<dbname> |
||||
``` |
||||
|
||||
Then, to restore the PostgreSQL dump please use the `pg_restore` command utility: |
||||
|
||||
```bash |
||||
pg_restore -h <dbhost> -p <dbport> -U <dbusername> -d <dbname> postgresql-dump-20191119210038.pgdump |
||||
``` |
||||
|
||||
Example: |
||||
|
||||
```bash |
||||
$ openproject config:get DATABASE_URL |
||||
postgres://openproject:L0BuQvlagjmxdOl6785kqwsKnfCEx1dv@127.0.0.1:45432/openproject |
||||
|
||||
$ pg_restore -h 127.0.0.1 -p 45432 -U openproject -d openproject postgresql-dump-20191119210038.pgdump |
||||
``` |
||||
|
||||
### Restart the OpenProject processes |
||||
|
||||
Finally, restart all your processes as follows: |
||||
|
||||
```bash |
||||
sudo service openproject restart |
||||
``` |
||||
|
||||
## Docker-based installation |
||||
|
||||
Assuming you have a backup as per the procedure described in the [Backing up](./backing-up) guide, if at any point you want to restore from a backup, just put your backup back in `/var/lib/openproject` on your local host, and re-launch the docker container with the recommended options. |
||||
|
||||
For instance, assuming your backup was stored on S3: |
||||
|
||||
```bash |
||||
aws s3 cp --recursive s3://my-backup-bucket/openproject-backups/ /var/lib/openproject/ |
||||
|
||||
docker run -d -p 8080:80 --name openproject -e SECRET_KEY_BASE=secret \ |
||||
-v /var/lib/openproject/pgdata:/var/lib/postgresql/9.6/main \ |
||||
-v /var/lib/openproject/logs:/var/log/supervisor \ |
||||
-v /var/lib/openproject/static:/var/db/openproject \ |
||||
openproject/community:10 |
||||
``` |
||||
@ -1,59 +1,82 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Upgrading |
||||
priority: 7 |
||||
--- |
||||
|
||||
# Upgrading your OpenProject installation |
||||
|
||||
Note: this guide only applies if you've installed OpenProject using our DEB/RPM |
||||
packages. |
||||
In the rest of this guide, we assume that you have taken the necessary steps to [backup](./backing-up) your OpenProject installation before upgrading. |
||||
|
||||
## Package-based installation (DEB/RPM) |
||||
|
||||
Upgrading OpenProject is as easy as installing a newer OpenProject package and |
||||
running the `openproject configure` command. |
||||
|
||||
## Backup |
||||
<div class="alert alert-info" role="alert"> |
||||
Please note that the package-based installation uses different release channels for each MAJOR version of OpenProject. This means that if you want to switch from (e.g.) 9.x to 10.x, you will need to perform the steps described in the [installation section](../installation/packaged) to update your package sources to point to the newer release channel. The rest of this section is only applicable if you want to upgrade a (e.g.) 10.x version to a 10.y vesion. |
||||
</div> |
||||
|
||||
We try to ensure your upgrade path is as smooth as possible. This means that the below update + configure step should be the only change needed to get up to date with our packaged installation. |
||||
### Debian / Ubuntu |
||||
|
||||
In the event of an error during the migrations, you will still want to have a recent backup you can restore to before reaching out to us. This is especially important for MySQL installations, since it does not support transactional migrations with changes to the table schema and you will have to rollback these changes manually. For PostgreSQL, if the Rails migrations fail, all previous changes will be rolled back for you to try again, or to install the older packages. |
||||
```bash |
||||
sudo apt-get update |
||||
sudo apt-get install --only-upgrade openproject |
||||
sudo openproject configure |
||||
``` |
||||
|
||||
To perform a backup, run the following command |
||||
### CentOS / RHEL |
||||
|
||||
```bash |
||||
sudo openproject run backup |
||||
sudo yum update |
||||
sudo yum install openproject |
||||
sudo openproject configure |
||||
``` |
||||
|
||||
This will store the current database dump, attachments and config to `/var/db/openproject/backup`. For more information on the backup and restore mechanisms, [check our detailed backup guide](https://www.openproject.org/operations/backup/backup-guide-packaged-installation/). |
||||
### SuSE |
||||
|
||||
## Debian / Ubuntu |
||||
```bash |
||||
sudo zypper update openproject |
||||
sudo openproject configure |
||||
``` |
||||
|
||||
sudo apt-get update |
||||
sudo apt-get install --only-upgrade openproject |
||||
sudo openproject configure |
||||
|
||||
## CentOS / RHEL |
||||
<div class="alert alert-info" role="alert"> |
||||
|
||||
sudo yum update |
||||
sudo yum install openproject |
||||
sudo openproject configure |
||||
Using `openproject configure`, the wizard will display new steps that weren't available yet or had not been configured in previous installations. |
||||
|
||||
## SuSE |
||||
If you want to perform changes to your configuration or are unsure what steps are available, you can safely run `openproject reconfigure` to walk through the entire configuration process again. |
||||
|
||||
sudo zypper update openproject |
||||
sudo openproject configure |
||||
Note that this still takes previous values into consideration. Values that should not change from your previous configurations can be skipped by pressing `<Return>`. This also applies for steps with passwords, which are shown as empty even though they may have a value. Skipping those steps equals to re-use the existing value. |
||||
|
||||
</div> |
||||
|
||||
## Re-configuring the application |
||||
## Docker-based installation |
||||
|
||||
Using `openproject configure`, the wizard will display new steps that weren't available yet or had not been configured in previous installations. |
||||
If you want to perform changes to your configuration or are unsure what steps are available, you can safely run `openproject reconfigure` to walk through the entire configuration process again. |
||||
Upgrading a Docker container is easy. First, pull the latest version of the image: |
||||
|
||||
Note that this still takes previous values into consideration. Values that should not change from your previous configurations can be skipped by pressing `<Return>`. This also applies for steps with passwords, which are shown as empty even though they may have a value. Skipping those steps equals to re-use the existing value. |
||||
```bash |
||||
docker pull openproject/community:VERSION |
||||
# e.g. docker pull openproject/community:10 |
||||
``` |
||||
|
||||
Then stop and remove your existing container (we assume that you are running with the recommended production setup here): |
||||
|
||||
# Upgrading between major releases (DEB/RPM packages) |
||||
```bash |
||||
docker stop openproject |
||||
docker rm openproject |
||||
``` |
||||
|
||||
Finally, re-launch the container in the same way you launched it previously. |
||||
This time, it will use the new image: |
||||
|
||||
Since OpenProject 9.0.0 is a major upgrade, you will need to perform some basic manual steps to upgrade your package. |
||||
``` |
||||
docker run -d ... openproject/community:VERSION |
||||
``` |
||||
|
||||
First, please check that the package repository is correct. |
||||
Compare your local package repository with the one printed on your matching distribution on [our Download and Installation page](https://www.openproject.org/download-and-installation/) |
||||
# Upgrade notes |
||||
|
||||
## Upgrade notes for OpenProject 9.0 |
||||
**TODO: review** |
||||
|
||||
These following points are some known issues around the update to 9.0. |
||||
|
||||
@ -1,99 +0,0 @@ |
||||
# Backup your OpenProject installation |
||||
|
||||
**Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages. |
||||
|
||||
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-<date>.sql.gz` or a `postgresql-dump-<pgdump>` 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 `<dbuser>`, `<dbhost>` and `<dbname>` 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 <dbhost> -u <dbuser> -W <dbname> |
||||
``` |
||||
|
||||
|
||||
|
||||
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 <dbuser> -h <dbhost> -p <dbname> |
||||
``` |
||||
@ -1,170 +0,0 @@ |
||||
# Upgrade your pre-5.0 OpenProject installation (DEB/RPM Packages) |
||||
|
||||
Starting with OpenProject 4.1 stable releases will have their own branch on github. According to this the OpenProject release 6.0 is tracked via the stable/6 branch. We provide a stable branch `stable/<VERSION>` to contain all minor upgrades to OpenProject <VERSION>.x. |
||||
|
||||
For OpenProject 4.2, two packages existed: The OpenProject Core and Community Edition. |
||||
Starting with OpenProject 5.0, both editions have been integrated into the single OpenProject package, which now contains a standard set of the most-used plugins previously contained in the Community Edition. |
||||
|
||||
This guide contains two guides: |
||||
|
||||
* The upgrade guide for OpenProject Core 4.2. to OpenProject 6.0 |
||||
* The migration guide to OpenProject 6.0 from OpenProject Community Edition 4.2. |
||||
|
||||
Please jump directly to the part of this guide depending on your OpenProject version (Core Edition or Community Edition) and operating system. |
||||
|
||||
## Upgrading from OpenProject Core Edition 4.2 |
||||
|
||||
### Preliminary step: Remove the sources.list that defines the OpenProject Core Edition 4.2 |
||||
|
||||
To avoid trying to update the deprecated 4.2 package, remove the following entry: |
||||
|
||||
sudo rm -i /etc/apt/sources.list.d/openproject.list |
||||
|
||||
|
||||
### Debian 7.6 Wheezy 64bits server |
||||
|
||||
echo "deb https://deb.packager.io/gh/opf/openproject wheezy stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
sudo openproject configure |
||||
|
||||
### Ubuntu 14.04 Trusty 64bits server |
||||
|
||||
echo "deb https://deb.packager.io/gh/opf/openproject trusty stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list |
||||
sudo apt-get update |
||||
sudo apt-get install openproject |
||||
sudo openproject configure |
||||
|
||||
### Fedora 20 64bits server |
||||
|
||||
echo "[openproject] |
||||
name=Repository for opf/openproject application. |
||||
baseurl=https://rpm.packager.io/gh/opf/openproject/fedora20/stable/6 |
||||
enabled=1" | sudo tee /etc/yum.repos.d/openproject.repo |
||||
sudo yum install openproject |
||||
sudo openproject configure |
||||
|
||||
### CentOS / RHEL 6 64 bits server |
||||
|
||||
echo "[openproject] |
||||
name=Repository for opf/openproject application. |
||||
baseurl=https://rpm.packager.io/gh/opf/openproject/centos6/stable/6 |
||||
enabled=1" | sudo tee /etc/yum.repos.d/openproject.repo |
||||
sudo yum install openproject |
||||
sudo openproject configure |
||||
|
||||
### SUSE Linux Enterprise Server 12 |
||||
|
||||
sudo zypper addrepo "https://rpm.packager.io/gh/opf/openproject/sles12/stable/6" "openproject" |
||||
sudo zypper install openproject |
||||
sudo openproject configure |
||||
|
||||
## Migrating from OpenProject Community Edition 4.2 |
||||
|
||||
The `openproject-ce` package no longer exists, but you can migrate to the new OpenProject package, which contains all functionality that was previously contained in the Community Edition. |
||||
|
||||
The following steps were tested on Ubuntu and Debian machines with OpenProject Community Edition 4.2 installed. There may be variations for other distributions, please let us know If you can provide additional information to the migration path. |
||||
|
||||
### Step 1: Backup existing installation |
||||
|
||||
Before performing the migration, please backup your existing installation. While we will continue to use it and database migrations should run smoothly, please keep a backup at hand. |
||||
|
||||
To backup attachments, database and repository, use the following command: |
||||
|
||||
sudo openproject-ce run backup |
||||
|
||||
### Step 2: Shut down openproject-ce instance |
||||
|
||||
To avoid any further changes to the application, stop the web and worker processes: |
||||
|
||||
sudo openproject-ce scale web=0 worker=0 |
||||
|
||||
### Step 3: Confirm database connection details |
||||
|
||||
If you used autoinstall, the database name and database user name should equal `openproject_ce`. You can confirm this by running: |
||||
|
||||
sudo openproject-ce config:get DATABASE_URL |
||||
|
||||
Which should output something of the form |
||||
|
||||
mysql2://<username>:<password>@127.0.0.1:3306/<dbname> |
||||
|
||||
If the URI contains `openproject_ce` as the username and database name as the example above, we can simply continue. |
||||
Otherwise, note user-, database name and password just to be sure. |
||||
|
||||
### Step 4: Remove the openproject-ce package |
||||
|
||||
Remove the `openproject-ce` package from your system. For Debian/Ubuntu, run: |
||||
|
||||
sudo apt-get remove openproject-ce |
||||
|
||||
### Step 5: Remove the sources.list that defines the Community Edition package |
||||
|
||||
To avoid installing the deprecated 4.2 package, remove the following entry: |
||||
|
||||
sudo rm -i /etc/apt/sources.list.d/pkgr-openproject-community.list |
||||
|
||||
|
||||
### Step 6: Move the existing application and configuration files |
||||
|
||||
As the OpenProject 6.0 package is identitical to the core in regards to paths, you'll need to reference the configuration and application (e.g., attachments, SVN repositories) files to the path that is expected from the new package. |
||||
|
||||
# Move openproject-ce configuration |
||||
sudo mv /etc/openproject-ce /etc/openproject |
||||
|
||||
For repositories, there are references in the database to the old `/var/db/openproject-ce/svn/<repository>` locations, so we suggest to symlink them instead: |
||||
|
||||
# Symlink existing attachments and |
||||
sudo ln -s /var/db/openproject-ce /var/db/openproject |
||||
|
||||
### Step 7: Disable the Community Edition Apache2 configuration |
||||
|
||||
As a final step, disable the `openproject-ce` configuration. |
||||
|
||||
sudo a2dissite openproject-ce |
||||
|
||||
Optionally, remove the disabled site. The following path applies to Debian/Ubuntu. |
||||
|
||||
sudo rm -i /etc/apache2/sites-available/openproject-ce.conf |
||||
|
||||
Note: |
||||
|
||||
* For RedHat, the path should be changed to `/etc/httpd/conf.d/openproject-ce.conf`. |
||||
* For SLES, the path should be changed to `/etc/apache2/vhosts.d/openproject-ce.conf`. |
||||
|
||||
### Step 8: Install the OpenProject 6.0 package and select database |
||||
|
||||
The rest of the installation is mostly identical to the installation guide of the OpenProject 5.0 package: |
||||
https://www.openproject.org/open-source/packaged-installation/packaged-installation-guide/ |
||||
|
||||
Add the package source to your package manager, update the sources, and install the `openproject` package. (See the installation guide linked above for the detailed steps for the various distributions). |
||||
|
||||
**Important:** Instead of running `openproject configure`, run `openproject reconfigure`, which will lead you through the complete wizard. |
||||
|
||||
In the first step *mysql/autoinstall*, select the **reuse** option (Use an existing database). |
||||
|
||||
 |
||||
|
||||
Press OK for the following steps, which will simply take the existing values from your old configuration |
||||
|
||||
* MySQL IP or hostname |
||||
* MySQL port |
||||
|
||||
In the dialog `mysql/username`, enter `openproject_ce` if the Database URI from Step 4 contained it. If you chose a different user name in the original CE installation, it should already be set to this value. |
||||
|
||||
 |
||||
|
||||
In the dialog `mysql/password`, **leave the password empty**. It will use the value from your original installation. You can optionally enter the password you retrieved from the database URI from Step 4, but that should be identical. |
||||
|
||||
 |
||||
|
||||
And again, in the `mysql/db_name` step, enter `openproject_ce` if the Database URI from Step 4 contained it. If you chose a different database name in the original CE installation, it should already be set to this value. |
||||
|
||||
The other installation steps (mysql/db_source_host, mysql/ssl) may again be skipped by pressing OK, as they should still contain the old values from the Community Edition. |
||||
|
||||
There will be other new steps in the installation wizard for which we will provide additional information in the packager installation guide. |
||||
|
||||
Once the wizard has completed, the OpenProject instance should be updated to 6.0.x while re-using your existing database. |
||||
|
||||
**Note:** This last step is a workaround for the package upgrading process. We are working on making this step optional. |
||||
The workaround is necessary since since the package appname changed from `openproject-ce` to `openproject`, and the installer wizard automatically sets the database to the app name when selecting an automatic installation of MySQL. Instead, the updater should respect an existing database (user-) name in its configuration. |
||||
@ -1,68 +0,0 @@ |
||||
## OpenProject PostgreSQL migration guide to 9.6 |
||||
|
||||
This guide will lead you to the steps of upgrading your system PostgreSQL version to 9.6. |
||||
OpenProject 7.4.0 requires PostgreSQL 9.5+, so we're recommending to install to 9.6 directly. |
||||
|
||||
If you're upgrading to 7.4.0 without a 9.5+ database, your upgrade process will be terminated with a 'Database incompatibility warning'. You should not |
||||
|
||||
Since Ubuntu 14.04 (still supported by OpenProject) is still running on PostgreSQL 9.3., we're showing the |
||||
upgrade process for this distribution. Debian oldstable also uses PostgreSQL 9.4. as well. |
||||
|
||||
### Preparations for the upgrade |
||||
|
||||
Stop the current OpenProject workers |
||||
|
||||
```bash |
||||
service openproject stop |
||||
``` |
||||
|
||||
### Install the newer PostgreSQL version |
||||
|
||||
For Ubuntu 14.04: |
||||
|
||||
```bash |
||||
sudo add-apt-repository "deb http://apt.postgresql.org/pub/repos/apt/ trusty-pgdg main" |
||||
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - |
||||
sudo apt-get update |
||||
sudo apt-get install postgresql-9.6 |
||||
``` |
||||
|
||||
|
||||
For other versions of Ubuntu, see this answer on AskUbuntu: |
||||
https://askubuntu.com/questions/831292 |
||||
|
||||
Or check the download for repositories from PostgreSQL: |
||||
https://www.postgresql.org/download/ |
||||
|
||||
|
||||
### Upgrade of PostgreSQL |
||||
|
||||
|
||||
Stop the old cluster: |
||||
|
||||
```bash |
||||
pg_dropcluster 9.6 main --stop |
||||
``` |
||||
|
||||
Upgrade the cluster to 9.6 |
||||
|
||||
```bash |
||||
pg_upgradecluster -v 9.6 9.3 main |
||||
``` |
||||
|
||||
Remove the old cluster |
||||
|
||||
```bash |
||||
pg_dropcluster 9.3 main |
||||
``` |
||||
|
||||
Lastly, remove the ubuntu-provided version of 9.3: |
||||
|
||||
```bash |
||||
apt-get remove postgres postgresql-9.3 |
||||
``` |
||||
|
||||
### Upgrade OpenProject |
||||
|
||||
You can now continue with the regular upgrading guide as detailed on these pages: |
||||
[https://www.openproject.org/operations/upgrading/](https://www.openproject.org/operations/upgrading/) |
||||
|
After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 9.4 KiB |
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue