TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up and rename

Browse Source 
[ci skip]
pull/5269/head
Niels Lindenthal 8 years ago
parent 01fd649a2c
commit f16d51412d
15 changed files with 0 additions and 2211 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 24
      doc/operation_guides/docker/backup-guide.md
  2. 150
      doc/operation_guides/docker/installation-guide.md
  3. 16
      doc/operation_guides/docker/upgrade-guide.md
  4. 116
      doc/operation_guides/manual/backup-guide.md
  5. 44
      doc/operation_guides/manual/install-plugins.md
  6. 498
      doc/operation_guides/manual/installation-guide.md
  7. 433
      doc/operation_guides/manual/repository-integration.md
  8. 242
      doc/operation_guides/manual/upgrade-guide.md
  9. 71
      doc/operation_guides/packager/backup-guide.md
  10. 53
      doc/operation_guides/packager/install-plugins.md
  11. 339
      doc/operation_guides/packager/installation-guide.md
  12. 170
      doc/operation_guides/packager/upgrade-guide-legacy.md
  13. 55
      doc/operation_guides/packager/upgrade-guide.md
  14. 0
      doc/operations/incoming_emails.md
  15. 0
      doc/operations/system_requirements.md

24
doc/operation_guides/docker/backup-guide.md
Unescape View File

@ -1,24 +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.4/main \
-v /var/lib/openproject/logs:/var/log/supervisor \
-v /var/lib/openproject/static:/var/db/openproject \
openproject/community:5.0
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.

150
doc/operation_guides/docker/installation-guide.md
Unescape View File

@ -1,150 +0,0 @@
### 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/engine/installation/
### Quick Start
The fastest way to get an OpenProject instance up and running is to run the
following command:
docker run -it -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:5.0
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:
docker run -d -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:5.0
### 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, as well as ensuring that the logs persist on
your host machine in case something goes wrong.
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 those 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:
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.4/main \
-v /var/lib/openproject/logs:/var/log/supervisor \
-v /var/lib/openproject/static:/var/db/openproject \
openproject/community:5.0
Since we named the container, you can now stop it by running:
docker stop openproject
And start it again:
docker start openproject
If you want to destroy the container, run the following commands
docker stop openproject && docker rm openproject
### 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 as explained in the [CONFIGURATION][configuration-doc]
documentation.
Environment variables can be either passed directly on the command-line to the
Docker Engine, or via an environment file:
docker run -d -e KEY1=VALUE1 -e KEY2=VALUE2 ...
docker run -d --env-file path/to/file ...
[configuration-doc]: https://github.com/opf/openproject/blob/dev/doc/CONFIGURATION.md
### SMTP configuration
By default, the docker container will try to send emails via the local
`postfix` daemon. However emails sent this way are more than likely to fail or
end up in the spam inbox of your users. We recommend using an external SMTP
server to send your emails.
A good choice is [SendGrid](https://sendgrid.net), which offers a free plan
with up to 12000 emails per month. Just sign up on the website, and once your
account is provisioned, generate a new API key and copy it somewhere (it looks
like `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`).
You can also just use your SendGrid username and password, but this is less
secure.
You can then configure OpenProject with the following additonal 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):
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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" \
...
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.
### FAQ
* Can I use SSL?
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.
* Can I use an external (MySQL or PostgreSQL) database?
Yes. You can simply pass a custom `DATABASE_URL` environment variable on the
command-line, which could point to an external database. You can even choose to
use MySQL instead of PostgreSQL if you wish. Here is how you would do it:
docker run -d ... -e DATABASE_URL=mysql2://user:pass@host:port/dbname openproject/community:5.0
The container will make sure that the database gets the migrations and demo
data as well.

16
doc/operation_guides/docker/upgrade-guide.md
Unescape View File

@ -1,16 +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:5.0
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:5.0

116
doc/operation_guides/manual/backup-guide.md
Unescape View File

@ -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.

44
doc/operation_guides/manual/install-plugins.md
Unescape View File

@ -1,44 +0,0 @@
# Install plugins (manual)
OpenProject plugins come under the form of Ruby gems. The packaged and docker
based installation come with default plugins installed (the ones found in the
[Community Edition of OpenProject](https://github.com/opf/openproject-ce)).
For a manual installation, you can choose to install a different set of plugins
by following the instructions below.
## How to install a plugin
You can install plugins by listing them in a file called `Gemfile.plugins`. An
example `Gemfile.plugins` file looks like this:
```
# Required by backlogs
gem "openproject-pdf_export", git: "https://github.com/finnlabs/openproject-pdf_export.git", :branch => "stable/5"
gem "openproject-backlogs", git: "https://github.com/finnlabs/openproject-backlogs.git", :branch => "stable/5"
```
If you have modified the `Gemfile.plugins` file, always repeat the following
steps of the OpenProject installation:
```bash
[openproject@debian]# cd ~/openproject-ce
[openproject@debian]# bundle install
[openproject@debian]# bower install
[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate db:seed assets:precompile
```
Restart the OpenProject server afterwards (no need to restart Apache(:
```bash
[openproject@debian]# touch ~/openproject-ce/tmp/restart.txt
```
The next request to the server will take longer (as the application is
restarted). All subsequent request should be as fast as always.
Always make sure that the plugin version is compatible with your OpenProject
version (e.g. use the ‘stable’ branch of both software -- OpenProject, and the
plugin).

498
doc/operation_guides/manual/installation-guide.md
Unescape View File

@ -1,498 +0,0 @@
# Installation of OpenProject 6.1 with Apache on Ubuntu 14.04. LTS
This tutorial helps you to deploy OpenProject 6.1. Please, aware that:
This guide requires that you have a clean Ubuntu 14.04 x64 installation
with administrative rights. We have tested the installation guide on an
Ubuntu Server image, but it should work on any derivative.
OpenProject will be installed with a MySQL database (the guide should
work similarly with PostgreSQL).
OpenProject will be served in a production environment with Apache
(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.
# Prepare Your Environment
Create a dedicated user for OpenProject:
```bash
sudo groupadd openproject
sudo useradd --create-home --gid openproject openproject
sudo passwd openproject #(enter desired password)
```
## Installation of Essentials
```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 \
imagemagick libmagickcore-dev libmagickwand-dev \
libtool bison libffi-dev git curl \
libxml2 libxml2-dev libxslt1-dev # nokogiri
```
## Installation of Memcached
```bash
[root@host] apt-get install -y memcached
```
## Installation of MySQL
```bash
[root@host] apt-get install mysql-server libmysqlclient-dev
```
During the installation you will be asked to set the root password.
We use the following command to open a `mysql` console and create
the OpenProject database.
```bash
[root@host] mysql -uroot -p
```
You may replace the string `openproject` with the desired username and
database name. The password `my_password` should definitely be changed.
```sql
mysql> CREATE DATABASE openproject CHARACTER SET utf8;
mysql> CREATE USER 'openproject'@'localhost' IDENTIFIED BY 'my_password';
mysql> GRANT ALL PRIVILEGES ON openproject.* TO 'openproject'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> QUIT
```
## 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 finsih.
```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.3.0
[openproject@host] rbenv rehash
[openproject@host] rbenv global 2.3.0
```
To check our Ruby installation we run `ruby --version`. It should output
something very similar to:
```
ruby 2.3.0p0 (2015-12-25 revision 53290) [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 finsih.
```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 6.9.1
[openproject@host] nodenv rehash
[openproject@host] nodenv global 6.9.1
```
To check our Node installation we run `node --version`. It should output
something very similar to:
```
v6.9.1
```
## 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-ce.
```bash
[openproject@host] cd ~
[openproject@host] git clone https://github.com/opf/openproject-ce.git --branch stable/6 --depth 1
[openproject@host] cd openproject-ce
[openproject@host] gem install bundler
[openproject@host] bundle install --deployment --without postgres 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-ce 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.
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: mysql2
database: openproject
host: localhost
username: openproject
password: my_password
encoding: utf8
development:
adapter: mysql2
database: openproject
host: localhost
username: openproject
password: my_password
encoding: utf8
```
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
```
Starting with 5.0, OpenProject directly manages your repositories. To
use this feature you have to configure OpenProject as shown
[here](./repository-integration.md).
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-ce
[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-threaded-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-ce
[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-ce/public
<Directory /home/openproject/openproject-ce/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-ce; /home/openproject/.rvm/gems/ruby-2.1.5/wrappers/rake jobs:workoff
```
This will start the worker job every minute.
## Repository Integration
OpenProject can (by default) browse Subversion and Git repositories, but it does not serve them to git/svn clients.
We do however support an integration with the Apache webserver to create and serve repositories on the fly, including integration into the fine-grained project authorization system of OpenProject.
OpenProject ships with support for so-called *managed* repositories, which can be created and maintained directly within OpenProject and are linked to a single project.
The complete guide for the integration of Subversion and Git repositories can be found in the [repository integration guide](repository-integration.md).
## Follow-Ups
Your OpenProject installation is ready to run. However, there are some things to consider:
* Regularly backup your OpenProject installation. See the [backup guide](backup-guide.md) for details.
* Serve OpenProject via https
* Watch for OpenProject updates. We advise to always run the latest stable version of OpenProject (especially for security updates). Information on how to perform an update can been found in the [upgrade guide](upgrade-guide.md). You can find out about new OpenProject releases in our [news](https://community.openproject.org/projects/openproject/news), or on [twitter](https://twitter.com/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-ce
[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-ce/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-ce/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-ce/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-ce/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).
* **I get an error during @bower install@. What can I do?**
We heard that `bower install` can fail, if your server is behind a firewall which does not allow `git://` URLs. The error looks like this:
```
ECMDERR Failed to execute "git ls-remote --tags --heads git://github.com/finnlabs/angular-modal.git", exit code of #128
Additional error details:
fatal: unable to connect to github.com:
github.com[0: 192.30.252.131]: errno=Connection refused
npm ERR! OpenProject@0.1.0 postinstall: `./node_modules/bower/bin/bower install`
```
The solution is to configure git to use `https://` URLs instead of `git://` URLs lke this:
```bash
git config --global url."https://".insteadOf git://
```
## 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.

433
doc/operation_guides/manual/repository-integration.md
Unescape View File

@ -1,433 +0,0 @@
# Repository Integration in OpenProject
OpenProject can (by default) browse Subversion and Git repositories, but it does not serve them to git/svn clients.
We do however support an integration with the Apache webserver to create and serve repositories on the fly, including integration into the fine-grained project authorization system of OpenProject.
## Existing Repositories
Using the default configuration, OpenProject allows you to *link* existing Subversion and Git repositories from the local filesystem (For Subversion, you can also integrate repositories from other servers using basic auth credentials).
When you link these repositories in OpenProject, you may browse the repository through OpenProject.
This functionality is extended with managed repositories, whose life spans are actively controlled by OpenProject. You can explicitly create local repositories for a project and configure repository access using permission the existing access-control functionality on a per-project level.
## Managed Repositories
You can create repositories explicitly on the filesystem using *managed* repositories.
Managed repositories need to be enabled manually for each SCM vendor individually using the `configuration.yml`.
It contains a YAML configuration section for repository management residing under the namespace `scm`.
The following is an excerpt of the configuration and contains all required information to set up your data.
# Configuration of Source control vendors
# client_command:
# Use this command to the default SCM vendor command (taken from path).
# Absolute path (e.g. /usr/local/bin/hg) or command name (e.g. hg.exe, bzr.exe)
# On Windows, *.cmd, *.bat (e.g. hg.cmd, bzr.bat) does not work.
# manages:
# You may either specify a local path on the filesystem or an absolute URL to call when
# repositories are to be created or deleted.
# This allows OpenProject to take control over the given path to create and delete repositories
# directly when created in the frontend.
#
# When entering a URL, OpenProject will POST to this resource when repositories are created
# using the following JSON-encoded payload:
# - action: The action to perform (create, delete)
# - identifier: The repository identifier name
# - vendor: The SCM vendor of the repository to create
# - project: identifier, name and ID of the associated project
# - old_identifier: The identifier to the old repository (used only during relocate)
#
# NOTE: Disabling :managed repositories using disabled_types takes precedence over this setting.
#
# disabled_types:
# Disable specific repository types for this particular vendor. This allows
# to restrict the available choices a project administrator has for creating repositories
# See the example below for available types
#
# Available types for git:
# - :local (Local repositories, registered using a local path)
# - :managed (Managed repositores, available IF :manages path is set below)
# Available types for subversion:
# - :existing (Existing subversion repositories by URL - local using file:/// or remote
# using one of the supported URL schemes (e.g., https://, svn+ssh:// )
# - :managed (Managed repositores, available IF :manages path is set below)
#
# Examplary configuration (Enables managed Git repositories at the given path)
scm:
git:
manages: /srv/repositories/git
With this configuration, you can create managed repositories by selecting the `managed` Git repository in the Project repository settings tab.
### Reposman.rb
Part of the managed repositories functionality was previously provided with reposman.rb.
Reposman periodically checked for new projects and automatically created a repository of a given type.
It never deleted repositories on the filesystem when their associated project was removed in OpenProject.
This script has been integrated into OpenProject and extended. If you previously used reposman, please see the [upgrade guide to 5.0](./upgrade-guide.md) for further guidance on how to migrate to managed repositories.
### Managing Repositories Remotely
OpenProject comes with a simple webhook to call other services rather than management repositories itself.
To enable remote managed repositories, simply pass an absolute URL to the `manages` key of a vendor in the `configuration.yml`. The following excerpt shows that configuration for Subversion, assuming your callback is `https://example.org/repos`.
scm:
subversion:
manages: https://example.org/repos
accesstoken: <Fixed access token passed to the endpoint>
Upon creating and deleting repositories in the frontend, OpenProject will POST to this endpoint a JSON object containg information on the repository.
{
"identifier": "seeded_project.git",
"vendor": "git",
"scm_type": "managed",
"project": {
"id": 1,
"name": "Seeded Project",
"identifier": "seeded_project"
},
"action": "create",
"token": <Fixed access token passed to the endpoint>
}
The endpoint is expected to return a JSON with at least a `message` property when the response is not successful (2xx).
When the response is successful, it must at least return a `url` property that contains an accessible URL, an optionally, a `path` property to access the repository locally.
Note that for Git repositories, OpenProject currently can only read them locally (i.e, through an NFS mount), so a path is mandatory here.
For Subversion, you can either return a `file:///<path>` URL, or a local path.
Our main use-case for this feature is to reduce the complexity of permission issues around Subversion mainly in packager, for which a simple Apache wrapper script is used in `extra/Apache/OpenProjectRepoman.pm`.
This functionality is very limited, but may be extended when other use cases arise.
It supports notifications for creating repositories (action `create`), moving repositories (action `relocate`, when a project's identifier has changed), and deleting repositories (action `delete`).
If you're interested in setting up the integration manually outside the context of packager, the following excerpt will help you:
PerlSwitches -I/srv/www/perl-lib -T
PerlLoadModule Apache::OpenProjectRepoman
<Location /repos>
SetHandler perl-script
# Sets the access token secret to check against
AccessSecret "<Fixed access token passed to the endpoint>"
# Configure pairs of (vendor, path) to the wrapper
PerlAddVar ScmVendorPaths "git"
PerlAddVar ScmVendorPaths "/srv/repositories/git"
PerlAddVar ScmVendorPaths "subversion"
PerlAddVar ScmVendorPaths "/srv/repositories/subversion"
PerlResponseHandler Apache::OpenProjectRepoman
</Location>
## Other Features
OpenProject 5.0 introduces more features regarding repository management that we briefly outline in the following.
### Checkout instructions
OpenProject 5.0 also integrates functionality to display checkout instructions and URLs for Subversion and Git repositories.
This functionality is very basic and will probably be made more robust over the next releases.
* Checkout instructions may be configured globally for each vendor
* Checkout URLs are constructed from a base URL and the project identifier
* On the repository page, the user is provided with a button to show/expand checkout instructions on demand.
* This checkout instruction contains the checkout URL for the given repository, and some further information on how the checkout works for this particular vendor (e.g., Subversion → svn checkout, Git → git clone).
* The instructions may contain information regarding the capabilities a user has (read, read-write)
* The instructions are defined by the SCM vendor implementations themselves, so that the checkout instructions may be extended by some 3rd party SCM vendor plugin
### Required Disk Storage Information
The total required disk space for a project (specifically, its repository and attachments) are listed in the projects administration pane, as well as the project setting overview.
This information is refreshed in the same manner that changesets are retrieved: By default, the repository is refreshed when a user visits the repository page. This information is cached for the time configured under the global `administration settings → repositories`.
You may also externally refresh this information using a cron job using the Sys API. Executing a GET against `/sys/projects/:identifier/repository/update_storage` will cause a refresh when the maximum cache time is expired. If you pass the query `?force=1` to the request above, it will ignore the cache.
For a future release, we are hoping to provide a webhook to update changesets and storage immediately after a change has been committed to the repository.
# Accessing repositories through Apache
With managed repositories, OpenProject takes care of the lifetime of repositories and their association with projects, however we still need to serve the repositories to the client.
## Preliminary Setup
In the remainder of this document, we assume that you run OpenProject but using a separate process, which listens for requests on http://localhost:3000 that you serve over Apache using a proxy.
We let Apache serve Subversion and git repositories (with the help of some modules) and
authenticate against the OpenProject user database.
Therefore we use an authentication perl script located in `extra/svn/OpenProjectAuthentication.pm`.
This script needs to be in your Apache perl path (for example it might be sym-linked into /etc/apache2/Apache).
To make the authentication work, you need to generate a secret repository API key, which you can generate in your OpenProject instance at `Modules → Administration → Settings → Repositories`.
On that page, enable *"Enable repository management web service"* and generate an API key (do not
forget to save the settings). We need that API key later in our Apache configuration.
You also need a distinct filesystem path for Subversion and Git repositories.
In this guide, we assume that you put your svn repositories in /srv/openproject/svn and your git repositories in /srv/openproject/git .
## Subversion Integration
Apache provides the module `mod_dav_svn` to serve Subversion repositories through HTTP(s).
This method requires some apache modules to be enabled and installed. The following commands are required for Debian / Ubuntu, please adjust accordingly for other distributions:
<pre>
apt-get install subversion libapache2-mod-perl2 libapache2-svn
a2enmod proxy proxy_http dav dav_svn
</pre>
### Permissions
**Important:** If Apache and OpenProject run under separate users, you need to ensure OpenProject remains the owner of the repository in order to browse and delete it, when requsted through the user interface.
Due to the implementation of `mod_svn`, we have no way to influence the permissions determined by apache when changing repositories (i.e., by committing changes).
Without correcting the permissions, the following situation will occur:
* The run user of OpenProject can correctly create and manage repository under the managed path with appropriate permissions set
* As soon as a user checks out the repository and commits new data
* Apache alters and adds files to the repository on the server, now owned by the apache user its default umask.
* If the user decides to delete the repository through the frontend
* Altered files are not / no longer owned or writable by the OpenProject user
* The deletion fails
The following workarounds exist:
#### Apache running `mod_dav_svn` and OpenProject must be run with the same user
This is a simple solution, but theoretically less secure when the server provides more than just SVN and OpenProject.
#### Use Filesystem ACLs
You can define ACLs on the managed repository root (requires compatible FS).
You'll need the the `acl` package and define the ACL.
Assuming the following situation:
* Apache run user / group: `www-data`
* OpenProject run user: `openproject`
* Repository path for SCM vendor X: `/srv/repositories/X`
# Set existing ACL
# Results in this ACL setting
# user::rwx
# user:www-data:rwx
# user:deploy:rwx
# group::r-x
# group:www-data:rwx
# mask::rwx
setfacl -R -m u:www-data:rwx -m u: openproject:rwx -m d:m:rwx /srv/repositories/X
# Promote to default ACL
# Results in
# default:user::rwx
# default:user:www-data:rwx
# default:user:deploy:rwx
# default:group::r-x
# default:group:www-data:rwx
# default:mask::rwx
# default:other::---
setfacl -dR -m u:www-data:rwx -m u:openproject:rwx -m m:rwx /srv/repositories/X
On many file systems, ACLS are enabled by default. On others, you might need to remount affected filesystems with the `acl` option set.
Note that this issue applies to mod_dav_svn only.
### Use the Apache wrapper script
Similar to the integration we use ourselves for the packager-based installation, you can set up Apache to manage repositories using the remote hook in OpenProject.
For more information, see the section 'Managing Repositories Remotely'.
### Exemplary Apache Configuration
We provide an example apache configuration. Some details are explained inline as comments.
# Load OpenProject per module used to authenticate requests against the user database.
# Be sure that the OpenProjectAuthentication.pm script is located in your perl path.
PerlSwitches -I/srv/www/perl-lib -T
PerlLoadModule Apache::OpenProjectAuthentication
<VirtualHost *:80>
ErrorLog /var/log/apache2/error
# The /sys endpoint is an internal API used to authenticate repository
# access requests. It shall not be reachable from remote.
<LocationMatch "/sys">
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
</LocationMatch>
# This fixes COPY for webdav over https
RequestHeader edit Destination ^https: http: early
# Serves svn repositories locates in /srv/openproject/svn via WebDAV
# It is secure with basic auth against the OpenProject user database.
<Location /svn>
DAV svn
SVNParentPath "/srv/openproject/svn"
# Avoid listing available repositories
SVNListParentPath Off
# Prefer bulk updates for improved performance
# Enable when SVN on server is >= 1.8
# SVNAllowBulkUpdates Prefer
# Avoid path-based authorization
SVNPathAuthz Off
# Caching options
SVNInMemoryCacheSize 131072
SVNCacheTextDeltas On
SVNCacheFullTexts On
DirectorySlash Off
AuthType Basic
AuthName "OpenProject Subversion Server"
Require valid-user
PerlAccessHandler Apache::Authn::OpenProject::access_handler
PerlAuthenHandler Apache::Authn::OpenProject::authen_handler
OpenProjectUrl 'http://127.0.0.1:3000'
OpenProjectApiKey 'REPLACE WITH REPOSITORY API KEY'
<Limit OPTIONS PROPFIND GET REPORT MKACTIVITY PROPPATCH PUT CHECKOUT MKCOL MOVE COPY DELETE LOCK UNLOCK MERGE>
Allow from all
</Limit>
# Requires the apache module mod_proxy. Enable it with
# a2enmod proxy proxy_http
# See: http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#ProxyPass
# Note that the ProxyPass with the longest path should be listed first, otherwise
# a shorter path may match and will do an early redirect (without looking for other
# more specific matching paths).
ProxyPass /svn !
ProxyPass / http://127.0.0.1:3000/
ProxyPassReverse / http://127.0.0.1:3000/
</Location>
## Git Integration
We can exploit git-http-backend to serve Git repositories through HTTP(s) with Apache.
This method additionally requires the `cgi` Apache module to be installed. The following commands are required for Debian / Ubuntu, please adjust accordingly for other distributions:
<pre>
apt-get install git libapache2-mod-perl2
a2enmod proxy proxy_http cgi
</pre>
You need to locate the location of the `git-http-backend` CGI wrapper shipping with the Git installation.
Depending on your installation, it may reside in `/usr/libexec/git-core/git-http-backend`.
[More information on git-http-backend.](http://git-scm.com/docs/git-http-backend)
### Permissions
We create bare Git repositories in OpenProject with the [`--shared`](https://www.kernel.org/pub/software/scm/git/docs/git-init.html) option of `git-init` set to group-writable.
Thus, if you use a separate user for Apache and OpenProject, they need to reside in a common group that is used for repository management. That group must be set in the `configuration.yml` (see above).
### Exemplary Apache Configuration
We provide an example apache configuration. Some details are explained inline as comments.
# Load OpenProject per module used to authenticate requests against the user database.
# Be sure that the OpenProjectAuthentication.pm script is located in your perl path.
PerlSwitches -I/srv/www/perl-lib -T
PerlLoadModule Apache::OpenProjectAuthentication
<VirtualHost *:80>
ErrorLog /var/log/apache2/error
# The /sys endpoint is an internal API used to authenticate repository
# access requests. It shall not be reachable from remote.
<LocationMatch "/sys">
Order Deny,Allow
Deny from all
Allow from 127.0.0.1
</LocationMatch>
# This fixes COPY for webdav over https
RequestHeader edit Destination ^https: http: early
# Serves svn repositories locates in /srv/openproject/svn via WebDAV
# It is secure with basic auth against the OpenProject user database.
<Location /svn>
DAV svn
SVNParentPath "/srv/openproject/svn"
DirectorySlash Off
AuthType Basic
AuthName "Secured Area"
Require valid-user
PerlAccessHandler Apache::Authn::OpenProject::access_handler
PerlAuthenHandler Apache::Authn::OpenProject::authen_handler
OpenProjectUrl 'http://127.0.0.1:3000'
OpenProjectApiKey 'REPLACE WITH REPOSITORY API KEY'
<Limit OPTIONS PROPFIND GET REPORT MKACTIVITY PROPPATCH PUT CHECKOUT MKCOL MOVE COPY DELETE LOCK UNLOCK MERGE>
Allow from all
</Limit>
</Location>
# see https://www.kernel.org/pub/software/scm/git/docs/git-http-backend.html for details
# needs mod_cgi to work -> a2enmod cgi
SetEnv GIT_PROJECT_ROOT /srv/openproject/git
SetEnv GIT_HTTP_EXPORT_ALL
ScriptAlias /git/ /usr/lib/git-core/git-http-backend/
<Location /git>
Order allow,deny
Allow from all
AuthType Basic
AuthName "OpenProject GIT"
Require valid-user
PerlAccessHandler Apache::Authn::OpenProject::access_handler
PerlAuthenHandler Apache::Authn::OpenProject::authen_handler
OpenProjectGitSmartHttp yes
OpenProjectUrl 'http://127.0.0.1:3000'
OpenProjectApiKey 'REPLACE WITH REPOSITORY API KEY'
</Location>
# Requires the apache module mod_proxy. Enable it with
# a2enmod proxy proxy_http
# See: http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#ProxyPass
# Note that the ProxyPass with the longest path should be listed first, otherwise
# a shorter path may match and will do an early redirect (without looking for other
# more specific matching paths).
ProxyPass /svn !
ProxyPass /git !
ProxyPass / http://127.0.0.1:3000/
ProxyPassReverse / http://127.0.0.1:3000/
</VirtualHost>
## Other integrations
With OpenProject 5.0, the interface to create custom integrations for other SCM vendors was improved dramatically.
If you're interested in writing a custom integration for some other SCM vendor (such as Mercurial), feel free to contact the developers of OpenProject over Github.
One examplary integration is the Gitolite plugin, which serves Git repositories from OpenProject over SSH using [Gitolite](http://www.gitolite.com).
The plugin is available at https://github.com/oliverguenther/openproject-revisions_git.

242
doc/operation_guides/manual/upgrade-guide.md
Unescape View File

@ -1,242 +0,0 @@
# OpenProject 6.0.x to OpenProject 6.1 Debian/Ubuntu Upgrade Guide
Please look at the steps in the section about the upgrade to OpenProject 6.0. OpenProject 6.x is being released under the branch `stable/6`.
### When running with MySQL: Required changes in sql_mode
If you're upgrading to OpenProject 6.1.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 woker 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
[openproject@debian]# npm -g install bower
```
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
[openproject@debian]# bower --version
1.3.12
```
## 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
```
*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/).

71
doc/operation_guides/packager/backup-guide.md
Unescape View File

@ -1,71 +0,0 @@
# Backup your OpenProject installation (DEB/RPM Packages)
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:
```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 MySQL 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
```
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>
```
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:
```bash
openproject config:get DATABASE_URL
#=> e.g.: mysql2://dbusername:dbpassword@dbhost:dbport/dbname
```

53
doc/operation_guides/packager/install-plugins.md
Unescape View File

@ -1,53 +0,0 @@
# Install plugins (RPM/deb-packages)
Note: this guide only applies if you've installed OpenProject using our DEB/RPM
packages.
[A number of plugins](https://www.openproject.org/open-source/openproject-plugins/) exist
for use with OpenProject. Most plugins that are maintained by us are shipping
with OpenProject, however there are several plugins contributed by the
community.
Previously, using them in a packaged installation was not possible without
losing your changes on every upgrade. With the following steps, you can now use
third party plugins.
**Note**: We cannot guarantee upgrade compatibility for third party plugins nor
do we provide support for them. Please carefully check whether the plugins you
use are available in newer versions before upgrading your installation.
## 1. Add a custom Gemfile
If you have a plugin you wish to add to your packaged OpenProject installation,
create a separate Gemfile with the Gem dependencies, such as the following:
```
gem 'openproject-emoji', git: 'https://github.com/tessi/openproject-emoji.git', :branch => 'op-5-stable'
```
We suggest to store the Gemfile under `/etc/openproject/Gemfile.custom`, but
the choice is up to you, just make sure the `openproject` user is able to read
it.
## 2. Propagate the Gemfile to the package
You have to tell your installation to use the custom gemfile via a config setting:
```
openproject config:set CUSTOM_PLUGIN_GEMFILE=/etc/openproject/Gemfile.custom
```
## 3. Re-run the installer
To re-bundle the application including the new plugins, as well as running
migrations and precompiling their assets, simply re-run the installer while
using the same configuration as before.
```
openproject configure
```
Using `configure` will take your previous decisions in the installer and simply
re-apply them, which is an idempotent operation. It will detect the Gemfile
config option being set and re-bundle the application with the additional plugins.

339
doc/operation_guides/packager/installation-guide.md
Unescape View File

@ -1,339 +0,0 @@
# OpenProject installation via package manager
The installation of the OpenProject software can be done manually or via
official software-packages built by the [Packager.io][packager-io] service.
Using these software packages is highly recommended to reduce the pain of
installation and configuration errors: the software packages ship with a
configuration wizard, which will help you get everything up and running quickly.
[packager-io]: https://packager.io/gh/opf/openproject-ce
## Stack used by the Packager.io packages
* Apache 2 (web server) – this component provides the external interface,
handles SSL termination (if SSL is used) and distributes/forwards web
requests to the Unicorn processes.
* MySQL (database management system) – this component is used to store and
retrieve data. We do support PostgreSQL as well, but it is not part of the automatic wizard. To configure this instead, see below.
* Unicorn (application server) – this component hosts the actual application.
By default, there is two unicorn processes running in parallel on the app
server machine.
* Ruby 2.1 (MRI) and necessary libraries to run the OpenProject source code.
# Installation
The installation procedure assumes the following prerequisites:
* A server running one of the Linux distributions listed in the [system requirements]: https://www.openproject.org/systemrequirements
* A mail server that is accessible via SMTP that can be used for sending
notification emails. OpenProject supports authentication, yet does not
provide support for SMTP via SSL/TLS.
* If you intend to use SSL for OpenProject: A valid SSL certifificate along
with the private key file. The key MUST NOT be protected by a passphrase,
otherwise the Apache server won't be able to read it when it starts.
The following steps have to be performed to initiate the actual installation of
OpenProject via the package manager that comes with your Linux distribution.
Note that all commands should either be run as root or should be prepended with
`sudo`.
## Debian 8 Jessie
# install https support
sudo apt-get install apt-transport-https
wget -qO - https://deb.packager.io/key | sudo apt-key add -
echo "deb https://deb.packager.io/gh/opf/openproject-ce jessie stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list
sudo apt-get update
sudo apt-get install openproject
## Debian 7 Wheezy
# install https support
sudo apt-get install apt-transport-https
sudo wget -qO - https://deb.packager.io/key | apt-key add -
echo "deb https://deb.packager.io/gh/opf/openproject-ce wheezy stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list
sudo apt-get update
sudo apt-get install openproject
## Ubuntu 16.04 Xenial
wget -qO - https://deb.packager.io/key | sudo apt-key add -
echo "deb https://deb.packager.io/gh/opf/openproject-ce xenial stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list
sudo apt-get update
sudo apt-get install openproject
## Ubuntu 14.04 Trusty
wget -qO - https://deb.packager.io/key | sudo apt-key add -
echo "deb https://deb.packager.io/gh/opf/openproject-ce trusty stable/6" | sudo tee /etc/apt/sources.list.d/openproject.list
sudo apt-get update
sudo apt-get install openproject
## CentOS / RHEL 7.x
sudo rpm --import https://rpm.packager.io/key
echo "[openproject]
name=Repository for opf/openproject-ce application.
baseurl=https://rpm.packager.io/gh/opf/openproject-ce/centos7/stable/6
enabled=1" | sudo tee /etc/yum.repos.d/openproject.repo
sudo yum install openproject
## Suse Linux Enterprise Server 12
sudo rpm --import https://rpm.packager.io/key
sudo zypper addrepo "https://rpm.packager.io/gh/opf/openproject-ce/sles12/stable/6" "openproject"
sudo zypper install openproject
## Suse Linux Enterprise Server 11
wget https://rpm.packager.io/key -O packager.key && sudo rpm --import packager.key
sudo zypper addrepo "https://rpm.packager.io/gh/opf/openproject-ce/sles11/stable/6" "openproject"
sudo zypper install openproject
# Customization
The OpenProject installation wizard currently supports setting up for MySQL databases only. However, OpenProject itself supports both MySQL and PostgreSQL. To configure the package to use an existing database, see the section below. To install or configure a MySQL database, skip to _Configuration_.
The OpenProject package is configured through ENV parameters that are passed to the `openproject` user. You can read the current ENV parameters with `openproject run env`. To write/read individual parameters, use `openproject config:set PARAMETER=VALUE` and `openproject config:get PARAMETER`.
For instance if you wanted to change the session store you would do:
sudo openproject config:set SESSION_STORE=active_record_store
This is handy to configure options that are not available in the installer (yet). In most cases though, you should always try to `configure` the application first.
## Configuring for an existing a PostgreSQL database
The MySQL wizard of the OpenProject installer internally sets the `DATABASE_URL` (See [DATABASE_URL](http://edgeguides.rubyonrails.org/configuring.html) in the Rails Guides for more information).
You can set this `DATABASE_URL` parameter yourself to either a MySQL or PostgreSQL database URL.
openproject config:set DATABASE_URL="postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]
**Then, when configuring the addon, select skip in the MySQL installation wizard.** The database specified using the URL will be used by Rails automatically for preparing the database.
You can use these ENV parameters to customize OpenProject. See [OpenProject Configuration](https://github.com/opf/openproject/blob/dev/doc/CONFIGURATION.md).
# Package Configuration
After the installation of the OpenProject package the system has to be
configured to use this package and operate the OpenProject application.
Therefore the package includes a configuration wizard which can be started
using the following command:
openproject configure
Side note: The installer supports the configuration of necessary SSL
connections too. If required the corresponding SSL certificates (incl. keys)
have to be placed somewhere on the machine **before** running the installer (or
`reconfigure` the application later to enable the SSL support).
After you have completed the configuration wizard, the OpenProject instance
will be started automatically. You can log into the instance initially with the
user/password combination _admin/admin_. You will be asked to change this
password immediately after the first login.
# 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 TYPE=NUM
openproject logs [--tail|-n NUMBER]
openproject config:get VAR
openproject config:set VAR=VALUE
openproject reconfigure
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:
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
You can also find all the logs in `/var/log/openproject/`.
## 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).
Note that if you've 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.
## 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=2
WEB_TIMEOUT=15
RAILS_CACHE_STORE=memcache
SESSION_STORE=cache_store
# Upgrade to a newer version
Upgrading the OpenProject is as easy as installing a newer OpenProject package
and running the `openproject configure` command.
## Debian / Ubuntu
sudo apt-get update
sudo apt-get install --only-upgrade openproject
sudo openproject configure
## CentOS / RHEL
sudo yum update
sudo yum install openproject
sudo openproject configure
## SuSE
sudo zypper update openproject
sudo openproject configure
# Advanced
## Easy SSL setup via 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
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.
The last thing you have to do is have OpenProject actually use the SSL certificate. For that you will have to reconfigure OpenProject using `openproject reconfigure`. Keep everything the same except for the SSL option where you then provide the path to the certificate and private key given by `certbot-auto` which is `/etc/letsencrypt/live/mydomain.com/fullchain.pem` and `/etc/letsencrypt/live/mydomain.com/privkey.pem` respectively.
## Sendmail setup
If you want to use sendmail to send emails you may have to install postfix.
If it is not yet installed do so using your package manager, for instance:
```
sudo apt-get install postfix
```
Pick the "No Configuration" option during the installation.
Next backup the configuration in `/etc/postfix` and override `/etc/postfix/main.cf` with the following:
```
allow_percent_hack = no
biff = no
bounce_queue_lifetime = 2h
default_destination_concurrency_limit = 2
disable_vrfy_command = yes
initial_destination_concurrency = 2
maximal_queue_lifetime = 4h
message_size_limit = 4096
mydomain = [your domain]
myhostname = [this host fqdn]
mynetworks = [ip list, or hash file]
smtpd_banner = $myhostname - private smtp
smtpd_client_restrictions =
smtpd_helo_required = yes
smtpd_helo_restrictions =
smtpd_recipient_restrictions = permit_mynetworks, reject
smtpd_sender_restrictions =
strict_mime_encoding_domain = yes
strict_rfc821_envelopes = yes
```
Then restart postfix, e.g. using `service postfix restart` and configure OpenProject to use it through `openproject reconfigure` if it is not already done.
Now you should be able to send emails form your OpenProject installation.
To test that it works login into OpenProject and send a test email via Administration -> Settings -> Email notifications.
## Adding custom plugins to the installation
[A number of plugins](https://www.openproject.org/open-source/openproject-plugins/) exist for use with OpenProject. Most plugins that are maintained by us are shipping with OpenProject, however there are several plugins contributed by the community.
Previously, using them in a packaged installation was not possible without losing your changes on every upgrade. With the following steps, you can now use third party plugins.
**Note**: We cannot guarantee upgrade compatibility for third party plugins nor do we provide support for them. Please carefully check whether the plugins you use are available in newer versions before upgrading your installation.
#### 1. Add a custom Gemfile
If you have a plugin you wish to add to your packaged OpenProject installation, create a separate Gemfile with the Gem dependencies, such as the following:
```
gem 'openproject-emoji', git: 'https://github.com/tessi/openproject-emoji.git', :branch => 'op-5-stable'
```
We suggest to store the Gemfile under `/etc/openproject/Gemfile.custom`, but the choice is up to you, just make sure the `openproject` user is able to read it.
#### 2. Propagate the Gemfile to the package
You have to tell your installation to use the custom gemfile via a config setting:
```
openproject config:set CUSTOM_PLUGIN_GEMFILE=/etc/openproject/Gemfile.custom
```
#### 3. Re-run the installer
To re-bundle the application including the new plugins, as well as running migrations and precompiling their assets, simply re-run the installer while using the same configuration as before.
```
openproject configure
```
Using `configure` will take your previous decisions in the installer and simply re-apply them, which is an idempotent operation. It will detect the Gemfile config option being set and re-bundle the application.

170
doc/operation_guides/packager/upgrade-guide-legacy.md
Unescape View File

@ -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-ce 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-ce 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-ce application.
baseurl=https://rpm.packager.io/gh/opf/openproject-ce/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-ce application.
baseurl=https://rpm.packager.io/gh/opf/openproject-ce/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-ce/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).
![](https://dl.dropboxusercontent.com/u/270758/op/mysql-reuse.png)
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.
![](https://dl.dropboxusercontent.com/u/270758/op/mysql-username.png)
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.
![](https://dl.dropboxusercontent.com/u/270758/op/mysql-password.png)
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.

55
doc/operation_guides/packager/upgrade-guide.md
Unescape View File

@ -1,55 +0,0 @@
# Upgrading your OpenProject installation (DEB/RPM Packages)
Note: this guide only applies if you've installed OpenProject using our DEB/RPM
packages.
Upgrading OpenProject is as easy as installing a newer OpenProject package and
running the `openproject configure` command.
## Debian / Ubuntu
sudo apt-get update
sudo apt-get install --only-upgrade openproject
sudo openproject configure
## CentOS / RHEL
sudo yum update
sudo yum install openproject
sudo openproject configure
## SuSE
sudo zypper update openproject
sudo openproject configure
## Re-configuring the application
Using `openproject configure`, the wizard will display new steps that you weren't available or 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.
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.
# Upgrading between major releases (DEB/RPM packages)
Since OpenProject 6.0.0 is a major upgrade, you will need to perform some basic manual steps to upgrade your package.
If you have currently installed the stable 5.0.x release of OpenProject by using the `stable/5` package source,
you will need to adjust that package source.
### APT-based systems (Debian, Ubuntu)
- Update the reference to `stable/5` in `/etc/apt/sources.list.d/openproject.list` to `stable/6`.
- Perform the Upgrade steps as mentioned above in *Upgrading your OpenProject installation*
### YUM-based systems (CentOS, RHEL)
- Update the reference to `stable/5` in `/etc/yum.repos.d/openproject.repo` to `stable/6`.
- Perform the Upgrade steps as mentioned above in *Upgrading your OpenProject installation*
### SUSE Linux Enterprise Server 11, 11
- Update the reference to `stable/5` in `/etc/zypp/repos.d/openproject.repo` to `stable/6`.
- Perform the Upgrade steps as mentioned above in *Upgrading your OpenProject installation*

0
doc/operation_guides/incoming_emails.md → doc/operations/incoming_emails.md
Unescape View File

0
doc/operation_guides/system_requirements.md → doc/operations/system_requirements.md
Unescape View File

Write Preview
Loading…
Cancel
Save