From f16d51412d35387911592d614aa48c4dcbcb2f63 Mon Sep 17 00:00:00 2001 From: Niels Lindenthal Date: Tue, 21 Mar 2017 17:08:27 +0100 Subject: [PATCH] Clean up and rename [ci skip] --- doc/operation_guides/docker/backup-guide.md | 24 - .../docker/installation-guide.md | 150 ------ doc/operation_guides/docker/upgrade-guide.md | 16 - doc/operation_guides/manual/backup-guide.md | 116 ---- .../manual/install-plugins.md | 44 -- .../manual/installation-guide.md | 498 ------------------ .../manual/repository-integration.md | 433 --------------- doc/operation_guides/manual/upgrade-guide.md | 242 --------- doc/operation_guides/packager/backup-guide.md | 71 --- .../packager/install-plugins.md | 53 -- .../packager/installation-guide.md | 339 ------------ .../packager/upgrade-guide-legacy.md | 170 ------ .../packager/upgrade-guide.md | 55 -- .../incoming_emails.md | 0 .../system_requirements.md | 0 15 files changed, 2211 deletions(-) delete mode 100644 doc/operation_guides/docker/backup-guide.md delete mode 100644 doc/operation_guides/docker/installation-guide.md delete mode 100644 doc/operation_guides/docker/upgrade-guide.md delete mode 100644 doc/operation_guides/manual/backup-guide.md delete mode 100644 doc/operation_guides/manual/install-plugins.md delete mode 100644 doc/operation_guides/manual/installation-guide.md delete mode 100644 doc/operation_guides/manual/repository-integration.md delete mode 100644 doc/operation_guides/manual/upgrade-guide.md delete mode 100644 doc/operation_guides/packager/backup-guide.md delete mode 100644 doc/operation_guides/packager/install-plugins.md delete mode 100644 doc/operation_guides/packager/installation-guide.md delete mode 100644 doc/operation_guides/packager/upgrade-guide-legacy.md delete mode 100644 doc/operation_guides/packager/upgrade-guide.md rename doc/{operation_guides => operations}/incoming_emails.md (100%) rename doc/{operation_guides => operations}/system_requirements.md (100%) diff --git a/doc/operation_guides/docker/backup-guide.md b/doc/operation_guides/docker/backup-guide.md deleted file mode 100644 index c9c8f5134d..0000000000 --- a/doc/operation_guides/docker/backup-guide.md +++ /dev/null @@ -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. - diff --git a/doc/operation_guides/docker/installation-guide.md b/doc/operation_guides/docker/installation-guide.md deleted file mode 100644 index 281b9aa8bf..0000000000 --- a/doc/operation_guides/docker/installation-guide.md +++ /dev/null @@ -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 -. 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. - diff --git a/doc/operation_guides/docker/upgrade-guide.md b/doc/operation_guides/docker/upgrade-guide.md deleted file mode 100644 index aea767eeec..0000000000 --- a/doc/operation_guides/docker/upgrade-guide.md +++ /dev/null @@ -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 - diff --git a/doc/operation_guides/manual/backup-guide.md b/doc/operation_guides/manual/backup-guide.md deleted file mode 100644 index 1bcc9e7ef1..0000000000 --- a/doc/operation_guides/manual/backup-guide.md +++ /dev/null @@ -1,116 +0,0 @@ -# Backup Guide - -We advice to backup your OpenProject installation regularly — especially before upgrading to a newer version. - -## Backup the Database - -###OpenProject Version 3.0.15 and newer - -Execute the following command in a shell in the directory where OpenProject is installed: - -```bash -RAILS_ENV=production bundle exec rake backup:database:create -``` - -The command will create dump of your database which can be found at `OPENPROJECT_DIRECTORY/backup/openproject-production-db-.sql` (for MySQL) or `OPENPROJECT_DIRECTORY/backup/openproject-production-db-.backup` (for PostgreSQL). - -Optionally, you can specify the path of the backup file. Therefore you have to replace the `/path/to/file.backup` with the path of your choice - -```bash -RAILS_ENV=production bundle exec rake backup:database:create[/path/to/backup/file.backup] -``` -*Note:* You can restore any database backup with the following command. Be aware that you have to replace the `/path/to/backup/file.backup` path with your actual backup path. - -```bash -RAILS_ENV=production bundle exec rake backup:database:restore[/path/to/backup/file.backup] -``` - -If your database dump is from an old version of OpenProject, also run the following command after the restore: - -```bash -RAILS_ENV=production bundle exec rake db:migrate -``` - -to migrate your data to the database structure of your installed OpenProject version. - -### OpenProject prior Version 3.0.15 - -Determine which Database you are using. You can find the relevant information in the `OPENPROJECT_DIRECTORY/config/database.yml` file. It looks similar to this: - -```yaml -production: - adapter: postgresql - database: openproject-production - host: localhost - username: my_postgres_user - password: my_secret_password - encoding: utf8 - min_messages: warning -``` - -Locate the database entry for your production database. If your adapter is postgresql, then you have a PostgreSQL database. If it is mysql2, you use a MySQL database. Now follow the steps for your database adapter. - -#### PostgreSQL -You can backup your PostgreSQL database with the `pg_dump` command and restore backups with the `pg_restore` command. (There might be other (and more convenient) tools, like pgAdmin, depending on your specific setup.) - -An example backup command with `pg_dump` looks like this: - -```bash -pg_dump --clean --format=custom --no-owner --file=/path/to/your/backup/file.backup --username=POSTGRESQL_USER --host=HOST DATABASE_NAME -``` - -Please, replace the path to your backup file, the username, host, and database name with your actual data. You can find all relevant information in the database.yml file. - -Consult the man page of `pg_dump` for more advanced parameters, if necessary. - -The database dump can be restored similarly with `pg_restore`: - -```bash -pg_restore --clean --no-owner --single-transaction ---dbname=DATABASE_NAME --host=HOST --username=POSTGRESQL_USER -/path/to/your/backup/file.backup -``` - -Consult the man page of `pg_restore` for more advanced parameters, if necessary. - -#### MySQL -You can backup your MySQL database for example with the mysqldump command and restore backups with the mysql command line client. (There might be other (and more convenient) tools, like phpMyAdmin, adminer, or other tools, depending on your specific setup.) - -An example backup command with `mysqldump` looks like this: - -```bash -mysqldump --single-transaction --add-drop-table --add-locks --result-file=/path/to/your/backup/file.sql --host=HOST --user=MYSQL_USER --password DATABASE_NAME -``` - -Please, replace the path to your backup file, the MySQL username, host and database name with your actual data. You can find all relevant information in the `database.yml` file. - -Consult the man page of `mysqldump` for more advanced parameters, if necessary. - -The database dump can be restored similarly with `mysql` (on a \*nix compatible shell): - -```bash -mysql --host=HOST --user=MYSQL_USER --password DATABASE_NAME < /path/to/your/backup/file.sql -``` -Consult the man page of mysql for more advanced parameters, if necessary. - -## Backup your Configuration Files -Please make sure to create a backup copy of at least the following configuration files (all listed as a relative path from the OpenProject installation directory): - -`Gemfile.local` (if present) -`Gemfile.plugins` (if present) -`config/database.yml` (if present) -`config/configuration.yml` (if present) -`config/settings.yml` (if present) - -Some OpenProject options can be given as environment variables. If you have configured environment variables for OpenProject, consider to backup them too. - -## Backup Files Uploaded by Users (attachments) -Files uploaded by users (e.g. when adding an attachment to a WorkPackage) are stored on the hard disk. The directory where those files are stored can be configured in the `config/configuration.yml` via the `attachments_storage_path` setting (or an -appropriate environment variable). - -If you have not changed the `attachment_storage_path` setting, all files will be uploaded to the files directory (relative to your OpenProject installation). - -Make sure to backup this directory. - -## Backup Repositories -You can manage Repositories with OpenProject — so one or more of your projects may have a repository. Please make sure to backup these too. The path to a project’s repository can be found in the repository settings of the respective project (it can be individually defined for every project). Each of the defined locations has to be backed up. diff --git a/doc/operation_guides/manual/install-plugins.md b/doc/operation_guides/manual/install-plugins.md deleted file mode 100644 index 59b6f23e90..0000000000 --- a/doc/operation_guides/manual/install-plugins.md +++ /dev/null @@ -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). - diff --git a/doc/operation_guides/manual/installation-guide.md b/doc/operation_guides/manual/installation-guide.md deleted file mode 100644 index 1da2d14968..0000000000 --- a/doc/operation_guides/manual/installation-guide.md +++ /dev/null @@ -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 - - 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 - -``` - -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 - - - ServerName yourdomain.com - # !!! Be sure to point DocumentRoot to 'public'! - DocumentRoot /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 - - - # Request browser to cache assets - - ExpiresActive On ExpiresDefault "access plus 1 year" - - - -``` - -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: -
/var/log/apache2/error.log
- -The OpenProject logfile can be found here: -
/home/openproject/openproject-ce/log/production.log
- -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: - 
/var/log/apache2/error.log
- The OpenProject log can be found here: - 
/home/openproject/openproject-ce/log/production.log
- -* **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. - diff --git a/doc/operation_guides/manual/repository-integration.md b/doc/operation_guides/manual/repository-integration.md deleted file mode 100644 index b97402f579..0000000000 --- a/doc/operation_guides/manual/repository-integration.md +++ /dev/null @@ -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: - -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": - } - -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:///` 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 - - - SetHandler perl-script - - # Sets the access token secret to check against - AccessSecret "" - - # 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 - - - -## 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: - -
-  apt-get install subversion libapache2-mod-perl2 libapache2-svn
-  a2enmod proxy proxy_http dav dav_svn
-
- -### 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 - - - 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. - - Order Deny,Allow - Deny from all - Allow from 127.0.0.1 - - - # 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. - - 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' - - - Allow from all - - - # 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/ - - -## 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: - -
-  apt-get install git libapache2-mod-perl2
-  a2enmod proxy proxy_http cgi
-
- -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 - - - 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. - - Order Deny,Allow - Deny from all - Allow from 127.0.0.1 - - - # 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. - - 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' - - - Allow from all - - - - # 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/ - - 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' - - - # 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/ - - - -## 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. diff --git a/doc/operation_guides/manual/upgrade-guide.md b/doc/operation_guides/manual/upgrade-guide.md deleted file mode 100644 index 8d352cfb39..0000000000 --- a/doc/operation_guides/manual/upgrade-guide.md +++ /dev/null @@ -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 - - PassengerRoot /home/openproject/.rvm/gems/ruby-2.1.4/gems/passenger-4.0.53 - PassengerDefaultRuby /home/openproject/.rvm/gems/ruby-2.1.4/wrappers/ruby - -``` -Please run the following commands to upgrade passenger and re-install the Apache module: - -```bash -[openproject@debian]# gem update passenger -[openproject@debian]# gem cleanup passenger -[openproject@debian]# passenger-install-apache2-module -``` - -The output of passenger-install-apache2-module2 tells you how to configure Apache. It is basically the same as what is already installed, except for the updated version numbers. - -Don’t forget to restart apache after the configuration change: - -```bash -[root@debian]# service apache2 reload -``` - -## Node.js installation -Node.js is necessary to precompile the assets (JavaScript and CSS). We will install the latest 0.12.x version of Node.js via nodeenv: - -```bash -[openproject@debian]# exit -[root@debian]# apt-get install python python-pip -[root@debian]# pip install nodeenv -[root@debian]# su - openproject -c "bash -l" -[openproject@debian]# cd /home/openproject -[openproject@debian]# nodeenv nodeenv -[openproject@debian]# source ./nodeenv/bin/activate -[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 #` 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/). - diff --git a/doc/operation_guides/packager/backup-guide.md b/doc/operation_guides/packager/backup-guide.md deleted file mode 100644 index 1b4bc5a2ac..0000000000 --- a/doc/operation_guides/packager/backup-guide.md +++ /dev/null @@ -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 -h -p -``` - -The ``, `` and `` variables have to be replaced with -the values that are container in the `DATABASE_URL` setting of your -installation. This setting can be seen by running: - -```bash -openproject config:get DATABASE_URL -#=> e.g.: mysql2://dbusername:dbpassword@dbhost:dbport/dbname -``` - diff --git a/doc/operation_guides/packager/install-plugins.md b/doc/operation_guides/packager/install-plugins.md deleted file mode 100644 index 2aa93b9800..0000000000 --- a/doc/operation_guides/packager/install-plugins.md +++ /dev/null @@ -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. - diff --git a/doc/operation_guides/packager/installation-guide.md b/doc/operation_guides/packager/installation-guide.md deleted file mode 100644 index 4a41dcd4d1..0000000000 --- a/doc/operation_guides/packager/installation-guide.md +++ /dev/null @@ -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. - diff --git a/doc/operation_guides/packager/upgrade-guide-legacy.md b/doc/operation_guides/packager/upgrade-guide-legacy.md deleted file mode 100644 index 7b8046df7c..0000000000 --- a/doc/operation_guides/packager/upgrade-guide-legacy.md +++ /dev/null @@ -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/` to contain all minor upgrades to OpenProject .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://:@127.0.0.1:3306/ - -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/` 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. diff --git a/doc/operation_guides/packager/upgrade-guide.md b/doc/operation_guides/packager/upgrade-guide.md deleted file mode 100644 index 17a8b80d95..0000000000 --- a/doc/operation_guides/packager/upgrade-guide.md +++ /dev/null @@ -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 ``. 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* diff --git a/doc/operation_guides/incoming_emails.md b/doc/operations/incoming_emails.md similarity index 100% rename from doc/operation_guides/incoming_emails.md rename to doc/operations/incoming_emails.md diff --git a/doc/operation_guides/system_requirements.md b/doc/operations/system_requirements.md similarity index 100% rename from doc/operation_guides/system_requirements.md rename to doc/operations/system_requirements.md