Merge branch 'documentation' of https://github.com/opf/openproject into documentation
birthe
5 years ago
commit
7408c24c89
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) |
||||
@ -0,0 +1,9 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Advanced configuration |
||||
priority: 100 |
||||
--- |
||||
|
||||
# Advanced configuration |
||||
|
||||
TODO |
||||
@ -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,9 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Other |
||||
priority: 0 |
||||
--- |
||||
|
||||
# Guides for infrequent operations |
||||
|
||||
TODO |
||||
@ -0,0 +1,9 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Operation |
||||
priority: 200 |
||||
--- |
||||
|
||||
# Operating OpenProject |
||||
|
||||
TODO |
||||
@ -0,0 +1,48 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Backing up |
||||
priority: 600 |
||||
--- |
||||
|
||||
# Backing up your OpenProject installation |
||||
|
||||
We advise to backup your OpenProject installation regularly — especially before upgrading to a newer version. |
||||
|
||||
## What should be backed up |
||||
|
||||
In general the following parts of your OpenProject installation should be backed up: |
||||
|
||||
- Data stored in the database |
||||
- Configuration files |
||||
- Uploaded files (attachments) |
||||
- Repositories (typically subversion) if applicable |
||||
|
||||
## Packaged installation (DEB/RPM) |
||||
|
||||
The DEB/RPM packages provide a backup tool which can be used to take a snaphsot |
||||
of the current OpenProject installation. This tool will create a backup of |
||||
all parts mentioned above. The backup tool is used by executing the following |
||||
command: |
||||
|
||||
``` |
||||
sudo openproject run backup |
||||
``` |
||||
|
||||
The command will create backup files in the following location on your system: |
||||
|
||||
``` |
||||
/var/db/openproject/backup |
||||
``` |
||||
|
||||
The content of that directory should look very similar to the following (depending on your database engine, you will see either a `mysql-dump-<date>.sql.gz` or a `postgresql-dump-<pgdump>` file). |
||||
|
||||
``` |
||||
root@test-packager-backup:/opt/openproject# ls -l /var/db/openproject/backup/ |
||||
total 24 |
||||
-rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz |
||||
-rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz |
||||
-rw-r----- 1 openproject openproject 8298 Apr 8 09:55 postgres-dump-20150408095521.sql.gz |
||||
-rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz |
||||
``` |
||||
|
||||
You should then copy those dump files to a secure location, for instance an S3 bucket or some sort of backup server. |
||||
@ -0,0 +1,25 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: (Re)configuring |
||||
priority: 800 |
||||
--- |
||||
|
||||
# (Re)configuring OpenProject |
||||
|
||||
## Packaged installation |
||||
|
||||
For packaged installations, you can restart the cofniguration process by issuing the following command on the server where OpenProject runs: |
||||
|
||||
``` |
||||
sudo openproject reconfigure |
||||
``` |
||||
|
||||
This will restart the installation wizard, and allow you to modify any of the choices that you previously selected. If a configuration options doesn't need to be modified, just hit `ENTER` to proceed to the next screen. |
||||
|
||||
## Docker installation |
||||
|
||||
For docker-based installations, you should update the environment file passed to the `--env-file` docker option, and issue the following command: |
||||
|
||||
``` |
||||
docker restart openproject |
||||
``` |
||||
@ -0,0 +1,75 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Restoring |
||||
priority: 500 |
||||
--- |
||||
|
||||
# Restoring an OpenProject backup |
||||
|
||||
## Packaged installation (DEB/RPM) |
||||
|
||||
Assuming you have a backup of all the OpenProject files at hand (see the [Backing up](../backing-up) guide), here is how you would restore your OpenProject installation from that backup. |
||||
|
||||
As a reference, we will assume you have the following dumps on your server, located in `/var/db/openproject/backup`: |
||||
|
||||
``` |
||||
-rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz |
||||
-rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz |
||||
-rw-r----- 1 openproject openproject 8298 Apr 8 09:55 postgres-dump-20150408095521.sql.gz |
||||
-rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz |
||||
``` |
||||
|
||||
### Stop the processes |
||||
|
||||
First, it is a good idea to stop the OpenProject instance: |
||||
|
||||
``` |
||||
sudo service openproject stop |
||||
``` |
||||
|
||||
### Restoring assets |
||||
|
||||
Untar the attachments to their destination: |
||||
|
||||
``` |
||||
tar xzf /var/db/openproject/backup/attachments-20150408095521.tar.gz -C /var/db/openproject/files/ |
||||
``` |
||||
|
||||
Untar the configuration to its destination: |
||||
|
||||
``` |
||||
tar xzf /var/db/openproject/backup/conf-20150408095521.tar.gz -C /etc/openproject/ |
||||
``` |
||||
|
||||
Untar the repositories to their destination: |
||||
|
||||
``` |
||||
tar xzf /var/db/openproject/backup/svn-repositories-20150408095521.tar.gz -C /var/db/openproject/repositories |
||||
``` |
||||
|
||||
### Restoring the database |
||||
|
||||
Note: in this section, the `<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: |
||||
|
||||
``` |
||||
openproject config:get DATABASE_URL |
||||
#=> e.g.: postgres://dbusername:dppassword@dbhost:dbport/dbname |
||||
``` |
||||
|
||||
Then, to restore the PostgreSQL dump please use the `psql` command utilities: |
||||
|
||||
``` |
||||
zcat /var/db/openproject/backup/postgres-dump-20150408095521.sql.gz | psql -h <dbhost> -u <dbusername> -W <dbname> |
||||
``` |
||||
|
||||
### Restart the OpenProject processes |
||||
|
||||
Finally, restart all your processes as follows: |
||||
|
||||
``` |
||||
sudo service openproject restart |
||||
``` |
||||
@ -1,11 +1,14 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Packaged installation |
||||
priority: 300 |
||||
title: Packages |
||||
priority: 400 |
||||
--- |
||||
|
||||
# Packaged installation (DEB/RPM) |
||||
|
||||
# Packaged installation |
||||
|
||||
TODO |
||||
The packaged installation is the recommended way to install OpenProject. Follow the instructions detailed in the following guides to get OpenProject running on your own server: |
||||
|
||||
| Main Topics | Description | |
||||
| ----------- | :---------- | |
||||
| [Installation](./installation) | How to install OpenProject from DEB/RPM packages | |
||||
| [Initial configuration](./configuration) | How to perform the initial configuration of OpenProject | |
||||
|
||||
@ -1,110 +0,0 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Backup Guide |
||||
priority: 50 |
||||
--- |
||||
|
||||
# Packaged installation backup guide |
||||
|
||||
<div class="alert alert-info" role="alert"> |
||||
|
||||
Note: this guide only applies if you've installed OpenProject using our DEB/RPM |
||||
packages. [Please see the index](../) for guides on other installation methods. |
||||
|
||||
</div> |
||||
|
||||
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> |
||||
``` |
||||
@ -0,0 +1,166 @@ |
||||
--- |
||||
sidebar_navigation: |
||||
title: Initial configuration |
||||
priority: 100 |
||||
--- |
||||
|
||||
# Initial configuration of your packaged installation |
||||
|
||||
After you have successfully installed the OpenProject package ([see the installation guide](../installation)), you can now perform the initial configuration of OpenProject, using the wizard that ships with the OpenProject package. |
||||
|
||||
## Prerequisites |
||||
|
||||
- If you wish to connect to an existing database server instead of setting up a local database server, please make sure to have your database hostname, port, username and password ready. The database username used to connect to the existing database must have the CREATE DATABASE privilege. |
||||
|
||||
- If you want to enable HTTPS, then you will need to provide the path (on the server) to your certificate file, private key file, and CA bundle file. |
||||
|
||||
## Step 0: start the wizard |
||||
|
||||
To start the configuration wizard, please run the following command with `sudo`, or as root: |
||||
|
||||
``` |
||||
sudo openproject configure |
||||
``` |
||||
|
||||
**Notes:** |
||||
|
||||
* In case you mistype or need to correct a configuratin option, you can always safely cancel the configuration wizard by pressing `CTRL+C` and restart it by running `sudo openproject reconfigure`. |
||||
|
||||
* Every time you will run the OpenProject wizard, your choices will be persisted in a configuration file at `/etc/openproject/installer.dat` and subsequent executions of `sudo openproject configure` will re-use these values, only showing you wizard steps for options you have not yet selected an option for. |
||||
|
||||
* In case you want to run through all wizard options again, you can do so by executing `sudo openproject reconfigure`. This will show all wizard steps, but again keep values you entered before showing in the input fields. You can skip dialogs you do not want to change simply by confirming them with `ENTER`. |
||||
|
||||
## Step 1: PostgreSQL database configuration |
||||
|
||||
The first dialog in the wizard allows you to choose an option for the PostgreSQL database connection: |
||||
|
||||
 |
||||
|
||||
The dialog allows you to choose from three options: |
||||
|
||||
### Install a new PostgreSQL server and database locally (default) |
||||
|
||||
Choose this option if you want OpenProject to set up and configure a local database server manually. This is the best choice if you are unfamiliar with adminstering databases, or do not have a separate PostgreSQL database server installed that you want to connect to. |
||||
|
||||
### Use an existing PostgreSQL database |
||||
|
||||
Choose this option if you have a PostgreSQL database server installed either on the same host as the OpenProject package is being installed on, or on another server you can connect to from this machine. |
||||
|
||||
The wizard will show you multiple additional steps in this case to enter the hostname, username & password as well as the database name for the PostgreSQL database. |
||||
|
||||
### Skip (not recommended) |
||||
|
||||
The wizard will not try to connect to any database. You will have to specify a database manually thorugh the `DATABASE_URL` environment variable. If you choose skip and did not set a `DATABASE_URL`, the configuration process will fail. |
||||
|
||||
You can set this `DATABASE_URL` parameter yourself to a PostgreSQL database URL. |
||||
|
||||
``` |
||||
sudo openproject config:set DATABASE_URL="postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] |
||||
``` |
||||
|
||||
## Step 2: Apache2 web server |
||||
|
||||
OpenProject comes with an internal ruby application server, but this server only listens on a local interface. To receive connections from the outside world, it needs a web server that will act as a proxy to forward incoming connections to the OpenProject application server. |
||||
|
||||
This wizard step allows you to auto-install an Apache2 web server to function as that proxy. |
||||
|
||||
 |
||||
|
||||
The available options are: |
||||
|
||||
### **Install Apache2 web server** (default) |
||||
|
||||
We recommend that you let OpenProject install and configure the outer web server, in which case we will install an Apache2 web server with a VirtualHost listening to the domain name you specify, optionally providing SSL/TLS termination. |
||||
|
||||
### **Skip** (not recommended) |
||||
|
||||
The installer will not set up an external web server for accessing. You will need to either install and set up a web server such as Apache2 or Nginx to function as the web server forwarding to our internal server listeing at `localhost:6000` by proxying. |
||||
|
||||
Only choose this option if you have a local Apache2 installed that the OpenProject package may not control, or need to use a different web server such as Nginx. Please note that not all functionality (especially regarding Repositories) are supported on Nginx. |
||||
|
||||
When installing with an existing Apache2, you can use our [installation wizard templates](https://github.com/pkgr/addon-apache2/tree/master/conf) for guidance on how to set up the integration. [For a minimal nginx config, please see this gist](https://gist.github.com/seLain/375d16ccd4542e3727e97a7478187d3a) as as starting point. |
||||
|
||||
In case you select to auto-install Apache2, multiple dialogs will request the parameters for setting it up. |
||||
|
||||
**Domain name** |
||||
|
||||
Enter the fully qualified domain where your OpenProject installation will be reached at. This will become the `ServerName` of your apache VirtualHost and is also used to generate full links from OpenProject, such as in emails. |
||||
|
||||
 |
||||
|
||||
**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) |
||||
|
||||
 |
||||
|
||||
## 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. |
||||
@ -0,0 +1,228 @@ |
||||
## Managing your OpenProject installation |
||||
|
||||
The openproject package comes with a command line tool to help manage the |
||||
application. To see all possible command options of this tool you can run: |
||||
|
||||
admin@openproject-demo:~# sudo openproject |
||||
Usage: |
||||
openproject run COMMAND [options] |
||||
openproject scale PROCESS=NUM |
||||
openproject logs [--tail|-n NUMBER] |
||||
openproject config:get VAR |
||||
openproject config:set VAR=VALUE |
||||
openproject config:unset VAR |
||||
openproject reconfigure |
||||
openproject restart [PROCESS] |
||||
|
||||
In the rest of this section we'll go over some of the most important commands. |
||||
|
||||
#### Run commands like rake tasks or rails console |
||||
|
||||
The openproject command line tool supports running rake tasks and known scripts |
||||
like the rails console: |
||||
|
||||
# Get the current version of OpenProject |
||||
sudo openproject run bundle exec rake version |
||||
# Or spawn an interactive console |
||||
sudo openproject run console |
||||
# or a rake task |
||||
sudo openproject run rake db:migrate |
||||
# or check the version of ruby used by openproject |
||||
sudo openproject run ruby -v |
||||
|
||||
#### Show logs |
||||
|
||||
The command line tool can also be used to see the log information. The most |
||||
typically use case is to show/follow all current log entries. This can be |
||||
accomplished using the the `–tail` flag. See example below: |
||||
|
||||
sudo openproject logs --tail |
||||
|
||||
Note: |
||||
|
||||
* On distributions that are based on systemd, all the logs are sent to journald, so you can also display them via `journalctl`. |
||||
* On older distributions that use either sysvinit or upstart, all the logs are stored in `/var/log/openproject/`. |
||||
|
||||
#### Scaling the number of web workers |
||||
|
||||
Depending on your free RAM on your system, we recommend you raise the default number of workers. The default from 9.0.3 onwards is four worker processes. Each worker will take roughly 300-400MB RAM. |
||||
|
||||
We recommend at least four workers. Please check your current worker count with |
||||
|
||||
```bash |
||||
sudo openproject config:get OPENPROJECT_WEB_WORKERS |
||||
``` |
||||
|
||||
If it returns nothing, the default worker count of `4` applies. To increase or decrease the worker count, call |
||||
|
||||
```bash |
||||
sudo openproject config:set OPENPROJECT_WEB_WORKERS=number |
||||
``` |
||||
|
||||
Where `number` is a positive number between 1 and `round(AVAILABLE_RAM * 1.5)`. |
||||
|
||||
After changing these values, call `sudo openproject configure` to apply it to the web server. |
||||
|
||||
#### Reconfigure the application |
||||
|
||||
At any point in time, you can reconfigure the whole application by re-running the installer with the following command: |
||||
|
||||
sudo openproject reconfigure |
||||
|
||||
The command above will bring up the installation wizard again. Please be aware that it will start the configuration/installation process from scratch. You can choose to modify existing entries, or just leave them as they are if you want to reuse them (note that passwords will appear as "blank" entries in their |
||||
respective input fields, but you don't need to enter them again if don't want to modify them). |
||||
|
||||
#### Upgrading the application |
||||
|
||||
As openproject is a system package, it will be automatically updated when you install your package updates. |
||||
|
||||
After you have just updated your OpenProject version, you should run `openproject configure` (see section below), which would automatically reuse your previous configuration, and only asks for your input if new configuration options are available. |
||||
|
||||
For a complete guide on upgrading your OpenProject packaged installation, [please see this guide](upgrading). |
||||
|
||||
#### Inspect the existing configuration |
||||
|
||||
You can list all of the environment variables accessible to the application by running: |
||||
|
||||
sudo openproject config |
||||
# this will return something like: |
||||
DATABASE_URL=mysql2://openproject:9ScapYA1MN7JQrPR7Wkmp7y99K6mRHGU@127.0.0.1:3306/openproject |
||||
SECRET_TOKEN=c5aa99a90f9650404a885cf5ec7c28f7fe1379550bb811cb0b39058f9407eaa216b9b2b22d27f58fb15ac21adb3bd16494ebe89e39ec225ef4627db048a12530 |
||||
ADMIN_EMAIL=mail@example.com |
||||
EMAIL_DELIVERY_METHOD=smtp |
||||
SMTP_DOMAIN=example.com |
||||
SMTP_HOST=smtp.example.com |
||||
SMTP_PASSWORD=mail |
||||
SMTP_PORT=25 |
||||
SMTP_URL=smtp://mail:mail@smtp.example.com:25/example.com |
||||
SMTP_USERNAME=mail |
||||
SMTP_ENABLE_STARTTLS_AUTO=true |
||||
SMTP_AUTHENTICATION=plain |
||||
WEB_CONCURRENCY=4 |
||||
WEB_TIMEOUT=15 |
||||
RAILS_CACHE_STORE=memcache |
||||
SESSION_STORE=cache_store |
||||
|
||||
|
||||
|
||||
# Frequently asked questions - FAQ |
||||
|
||||
## How can I install an OpenProject plugin? |
||||
|
||||
Our [official installation page][install-page] has instructions on how to customize your OpenProject installation. |
||||
Please note that customization is not yet supported for Docker-based installations. |
||||
|
||||
[install-page]: https://www.openproject.org/download-and-installation/ |
||||
|
||||
|
||||
|
||||
## How to migrate from Bitnami to the official OpenProject installation packages? |
||||
|
||||
Please follow the following steps: |
||||
|
||||
1. Make a dump of your bitnami database to export your data. You can refer to the [Bitnami documentation][bitnami-mysql]. |
||||
1. Make a dump of files your might have uploaded. You can refer to the [Bitnami documentation][bitnami-backup] to perform a full dump. |
||||
1. Copy both dumps to the server you want to install OpenProject on. |
||||
1. Install OpenProject using the packaged installation. |
||||
1. By default, this will allow you to install a PostgreSQL database, which we recommend. You can migrate your data from MySQL using https://pgloader.io |
||||
1. Import the dump into your new database. You can get your configuration by running `sudo openproject config:get DATABASE_URL` |
||||
1. Extract the bitnami backup, and copy your file assets into the relevant directory (e.g. in `/var/db/openproject/files` for uploaded files) |
||||
1. Restart OpenProject |
||||
|
||||
[bitnami-mysql]: https://docs.bitnami.com/installer/components/mysql/ |
||||
[bitnami-backup]: https://docs.bitnami.com/installer/apps/openproject/ |
||||
|
||||
|
||||
|
||||
## Can I use NginX instead of Apache webserver? |
||||
|
||||
Yes, but you will lose the ability to enable Git/SVN repository integration. Note that the OpenProject installer does not support NginX, so you will have to ask to disable the Apache2 integration when running the installer, and then configure NginX yourself so that it forwards traffic to the OpenProject web process (listening by default on 127.0.0.1:6000). If using SSL/TLS, please ensure you set the header value `X-Forwarded-Proto https` so OpenProject can correctly produce responses. [For more information, please visit our forums](https://community.openproject.com/projects/openproject/boards). |
||||
|
||||
|
||||
|
||||
## Can I use MySQL instead of PostgreSQL? |
||||
|
||||
OpenProject has traditionally supported both MySQL and PostgreSQL, but in order to optimize for performance and SQL functionality, it is unfeasible to support both DBMS that are becoming more and more disjunct when trying to use more modern SQL features. This shift has started some years ago when full-text search was added for PostgreSQL, but at the time MySQL did not yet support it - and as of yet many distributions still do not support MySQL 8 natively. |
||||
|
||||
This led us to the path of removing support in the upcoming stable releases of OpenProject in order to focus on these goals. [Please see our blog post on the matter for additional notes](https://www.openproject.org/deprecating-mysql-support/). |
||||
|
||||
|
||||
|
||||
## How can I migrate my existing MySQL database to PostgreSQL ? |
||||
|
||||
Older installations of OpenProject are likely installed with a MySQL installation because the installer shipped with an option to auto-install it. With [pgloader](https://pgloader.io), it is trivially easy to convert a dump between MySQL and PostgreSQL installation. [We have prepared a guide](https://www.openproject.org/operations/upgrading/migrating-packaged-openproject-database-postgresql/) on how to migrate to a PostgreSQL database if you previously used MySQL. |
||||
|
||||
|
||||
|
||||
## My favorite linux distribution is not listed. What can I do? |
||||
|
||||
You can either try the manual installation, or ask in the forum whether this could be added to the list of supported distributions. We try to support recent major distributions, but due to maintenance and operations cost cannot freely add to that list. |
||||
|
||||
|
||||
|
||||
## What is the better option to run OpenProject in production environments: docker or linux packages? |
||||
|
||||
We recommend the Linux packages [if you have a compatible distribution](https://www.openproject.org/system-requirements/) and a separate machine for OpenProject, since it will allow for the easiest and most flexible setup. Use a docker-based image either for quickly spinning up an environment or if you have knowledge in setting up and maintaing docker-based installations. |
||||
|
||||
Please note we currently do not yet provide a docker-compose based image, [please see this ticket for a timeline](https://community.openproject.com/wp/30551) and help us contribute one! |
||||
|
||||
|
||||
|
||||
## Do you provide different release channels? |
||||
|
||||
Yes! We release OpenProject in separate release channels that you can try out. For production environments, **always** use the `stable/MAJOR` (e.g., stable/9) package source that will receive stable and release updates. Every major upgrade will result in a source switch (from `stable/7` to `stable/8` for example). |
||||
|
||||
A closer look at the available branches: |
||||
|
||||
* [stable/9](https://packager.io/gh/opf/openproject/refs/stable/9): Latest stable releases, starting with 9.0.0 until the last minor and patch releases of 9.X.Y are released, this will receive updates. |
||||
* [release/9.0](https://packager.io/gh/opf/openproject/refs/release/9.0): Regular (usually daily) release builds for the current next patch release (or for the first release in this version, such as 9.0.0). This will contain early bugfixes before they are being release into stable. **Do not use in production**. But, for upgrading to the next major version, this can be regarded as a _release candidate channel_ that you can use to test your upgrade on a copy of your production environment. |
||||
* [dev](https://packager.io/gh/opf/openproject/refs/dev): Daily builds of the current development build of OpenProject. While we try to keep this operable, this may result in broken code and/or migrations from time to time. Use when you're interested what the next release of OpenProject will look like. **Do not use in production!** |
||||
|
||||
For more information, please visit our dedicated [page regarding release candidates and channels](https://www.openproject.org/download-and-installation/release-candidate/). |
||||
|
||||
|
||||
|
||||
## How to upgrade my OpenProject installation? |
||||
|
||||
Please refer to the documentation at https://www.openproject.org/operations/upgrading/ |
||||
|
||||
|
||||
|
||||
## What skills should I have for the installation? |
||||
|
||||
If you use the packaged installation, you should have a basic knowledge of Linux and the command-line terminal. |
||||
|
||||
If you use the docker images, you need to be familiar with Docker and Docker volumes. |
||||
|
||||
|
||||
|
||||
## Why don't you support Windows? |
||||
|
||||
Ruby support on Windows is notoriously difficult, however you might be able to run the Docker image, or use the unofficial Windows stack provided by [Bitnami](https://bitnami.com/stack/openproject/installer). We would welcome feedback and reported experiences on running OpenProject on Windows, please reach out to us if you can contribute some information. |
||||
|
||||
|
||||
|
||||
## How to backup and restore my OpenProject installation? |
||||
|
||||
Please refer to the [backup documentation](backup) for the packaged installation. |
||||
|
||||
|
||||
|
||||
## How can I install a free SSL certificate using let's encrypt? |
||||
|
||||
You can get an SSL certificate for free via Let's Encrypt. |
||||
Here is how you do it using [certbot](https://github.com/certbot/certbot): |
||||
|
||||
curl https://dl.eff.org/certbot-auto > /usr/local/bin/certbot-auto |
||||
chmod a+x /usr/local/bin/certbot-auto |
||||
|
||||
certbot-auto certonly --webroot --webroot-path /opt/openproject/public -d openprojecct.mydomain.com |
||||
|
||||
This requires your OpenProject server to be available from the Internet on port 443 or 80. |
||||
If this works the certificate (`cert.pem`) and private key (`privkey.pem`) will be created under `/etc/letsencrypt/live/openproject.mydomain.com/`. Configure these for OpenProject to use by running `openproject reconfigure` and choosing yes when the wizard asks for SSL. |
||||
|
||||
Now this Let's Encryt certificate is only valid for 90 days. To renew it automatically all you have to do is to add the following entry to your crontab (run `crontab -e`): |
||||
|
||||
0 1 * * * certbot-auto renew --quiet --post-hook "service apache2 restart" |
||||
|
||||
This will execute `certbot renew` every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate. |
||||
Loading…
Reference in new issue