From 5c9bb331bab6f41b963310e88c7f52d5f496867a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20G=C3=BCnther?= Date: Wed, 8 Mar 2017 10:52:13 +0100 Subject: [PATCH] Separate actual documentation guides in github from sources From now on, use `doc/` as a source folder for documentation assets to be built (e.g., API documentation or source files included in wordpress). Use `guides/` for self-reliant Markdown documents on topics relevant for developers and administrators, as well as community-contributed guides we do not feature on the website. [ci skip] --- README.md | 8 +- doc/README.md | 54 +- doc/RUNNING_TESTS_LDAP.rdoc | 11 - doc/UPGRADING.rdoc | 35 - doc/apiv2-documentation.md | 1525 ----------------- doc/subversion_and_git_integration.md | 9 - doc/wp/backup/backup-guide.md | 71 + doc/wp/installation/0-preparation.md | 30 + doc/wp/installation/1-installation.md | 3 + doc/wp/installation/2-configuration.md | 124 ++ doc/wp/installation/3-customization.md | 52 + doc/wp/installation/alternative-methods.md | 3 + doc/wp/installation/centos-7/steps.md | 31 + doc/wp/installation/debian-7/steps.md | 38 + doc/wp/installation/debian-8/steps.md | 38 + doc/wp/installation/sles-11/steps.md | 30 + doc/wp/installation/sles-12/steps.md | 30 + doc/wp/installation/ubuntu-14.04/steps.md | 29 + doc/wp/installation/ubuntu-16.04/steps.md | 29 + doc/wp/system_requirements.md | 52 + doc/wp/upgrading/upgrade-guide-legacy.md | 170 ++ doc/wp/upgrading/upgrade-guide.md | 55 + guides/README.md | 38 + guides/api/README.md | 18 + guides/backup/README.md | 12 + guides/backup/docker/README.md | 24 + guides/backup/manual/README.md | 116 ++ .../configuration/README.md | 29 - guides/development/README.md | 7 + .../development}/code-review-guidelines.md | 0 .../development/create-omniauth-plugin.md | 0 .../development/create-openproject-plugin.md | 0 .../development/quick-start.md | 29 - .../development/running-tests.md | 12 + .../setting-up-development-environment.md | 0 guides/incoming-mails/README.md | 130 ++ guides/installing/README.md | 18 + guides/installing/docker/README.md | 150 ++ guides/installing/manual/README.md | 477 ++++++ guides/repositories/README.md | 433 +++++ guides/upgrading/README.md | 12 + guides/upgrading/docker/README.md | 16 + guides/upgrading/manual/README.md | 239 +++ 43 files changed, 2501 insertions(+), 1686 deletions(-) delete mode 100644 doc/RUNNING_TESTS_LDAP.rdoc delete mode 100644 doc/UPGRADING.rdoc delete mode 100644 doc/apiv2-documentation.md delete mode 100644 doc/subversion_and_git_integration.md create mode 100644 doc/wp/backup/backup-guide.md create mode 100644 doc/wp/installation/0-preparation.md create mode 100644 doc/wp/installation/1-installation.md create mode 100644 doc/wp/installation/2-configuration.md create mode 100644 doc/wp/installation/3-customization.md create mode 100644 doc/wp/installation/alternative-methods.md create mode 100644 doc/wp/installation/centos-7/steps.md create mode 100644 doc/wp/installation/debian-7/steps.md create mode 100644 doc/wp/installation/debian-8/steps.md create mode 100644 doc/wp/installation/sles-11/steps.md create mode 100644 doc/wp/installation/sles-12/steps.md create mode 100644 doc/wp/installation/ubuntu-14.04/steps.md create mode 100644 doc/wp/installation/ubuntu-16.04/steps.md create mode 100644 doc/wp/system_requirements.md create mode 100644 doc/wp/upgrading/upgrade-guide-legacy.md create mode 100644 doc/wp/upgrading/upgrade-guide.md create mode 100644 guides/README.md create mode 100644 guides/api/README.md create mode 100644 guides/backup/README.md create mode 100644 guides/backup/docker/README.md create mode 100644 guides/backup/manual/README.md rename doc/CONFIGURATION.md => guides/configuration/README.md (90%) create mode 100644 guides/development/README.md rename {doc => guides/development}/code-review-guidelines.md (100%) rename {doc => guides}/development/create-omniauth-plugin.md (100%) rename {doc => guides}/development/create-openproject-plugin.md (100%) rename doc/QUICK_START.md => guides/development/quick-start.md (76%) rename doc/RUNNING_TESTS.md => guides/development/running-tests.md (94%) rename {doc => guides}/development/setting-up-development-environment.md (100%) create mode 100644 guides/incoming-mails/README.md create mode 100644 guides/installing/README.md create mode 100644 guides/installing/docker/README.md create mode 100644 guides/installing/manual/README.md create mode 100644 guides/repositories/README.md create mode 100644 guides/upgrading/README.md create mode 100644 guides/upgrading/docker/README.md create mode 100644 guides/upgrading/manual/README.md diff --git a/README.md b/README.md index 6bf05aca03b..18768955520 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ If you want to run an instance of OpenProject in production (or for evaluation), in-depth [installation guides](https://www.openproject.org/download/). If you're a developer wanting to set-up a local environment for contributing to OpenProject or -developing plugins, you should refer instead to our [Quick Start for Developers](doc/QUICK_START.md). +developing plugins, you should refer instead to our [Quick Start for Developers](./guides/development/quick-start.md). -Our [developer documentation](doc/README.md) also includes a [reference of configuration options](doc/CONFIGURATION.md). +For a complete reference to all community guides, [please see this document](./guides/README.md). ## Contact @@ -44,8 +44,10 @@ The [OpenProject Foundation (OPF)](https://community.openproject.org/projects/op This repository contains several main branches: +* `stable/`: Contains the latest stable release for a specific version. We recommend to use this for production use. Example: `stable/6`. * `dev`: The main development branch. We try to keep it stable in the sense of all tests are passing, but we don't recommend it for production systems. -* `stable/`: Contains the latest stable release for a specific version. We recommend to use this for production use. Example: `stable/4.1`. +* `release/.` the release branch for the immediate next patch release within the given major and minor version. Example `release/6.1` targets the unrelease next patch release `6.1.x`. + ## Security / Responsible Disclosure diff --git a/doc/README.md b/doc/README.md index 721423ae035..cd332c663ba 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,50 +1,18 @@ - - -OpenProject Developer Documentation -=================================== - -* [Quick Start for Developers](QUICK_START.md) -* [Configuration](CONFIGURATION.md) -* [Developing Plugins](DEVELOP_PLUGINS.md) -* [Running Tests](RUNNING_TESTS.md) -* [Upgrading](UPGRADING.rdoc) -* [API Documentation](#api-documentation) - -API Documentation ------------------ - -## API Version 3 - -_Status: under development_ - -The documentation for APIv3 is written in the [API Blueprint Format](http://apiblueprint.org/). +The documentation for APIv3 is written in the [API Blueprint Format](http://apiblueprint.org/) and its sources are being built from the entry point `apiv3-documentation.apib`. You can use [aglio](https://github.com/danielgtaylor/aglio) to generate HTML documentation, e.g. using the following command: @@ -52,8 +20,4 @@ You can use [aglio](https://github.com/danielgtaylor/aglio) to generate HTML doc aglio -i apiv3-documentation.apib -o api.html ``` -## API Version 2 - -_Status: deprecated_ - -Documentation may be found on our [API v2 wiki pages](https://community.openproject.org/projects/openproject/wiki/API_v2/). +The output of the API documentation at `dev` branch is continuously built and pushed to Github Pages at [opf.github.io/apiv3-doc/](opf.github.io/apiv3-doc/). \ No newline at end of file diff --git a/doc/RUNNING_TESTS_LDAP.rdoc b/doc/RUNNING_TESTS_LDAP.rdoc deleted file mode 100644 index 1073b3c3b6f..00000000000 --- a/doc/RUNNING_TESTS_LDAP.rdoc +++ /dev/null @@ -1,11 +0,0 @@ - -== Creating a test ldap database - -OpenProject supports using LDAP for user authentications. To test LDAP -with OpenProject, load the LDAP export from test/fixtures/ldap/test-ldap.ldif -into a testing LDAP server. Test that the ldap server can be accessed -at 127.0.0.1 on port 389. - -Setting up the test ldap server is beyond the scope of this documentation. -The OpenLDAP project provides a simple LDAP implementation that should work -good as a test server. diff --git a/doc/UPGRADING.rdoc b/doc/UPGRADING.rdoc deleted file mode 100644 index e2ac73d60a8..00000000000 --- a/doc/UPGRADING.rdoc +++ /dev/null @@ -1,35 +0,0 @@ -= Upgrade - -The detailed upgrade instructions are located on the {official website}[https://www.openproject.org/download/upgrade-guides/] - - ----------- -==== copyright - - OpenProject is a project management system. - Copyright (C) 2012-2015 the OpenProject Foundation (OPF) - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License version 3. - - OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows: - Copyright (C) 2006-2013 Jean-Philippe Lang - Copyright (C) 2010-2013 the ChiliProject Team - - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License - as published by the Free Software Foundation; either version 2 - of the License, or (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - - See doc/COPYRIGHT.rdoc for more details. - ++ ----------- diff --git a/doc/apiv2-documentation.md b/doc/apiv2-documentation.md deleted file mode 100644 index 7dd1ccbc5f0..00000000000 --- a/doc/apiv2-documentation.md +++ /dev/null @@ -1,1525 +0,0 @@ -# OpenProject REST API v2 Documentation - -__Be aware:__ The API v2 is marked as deprecated. Please read this [news article](https://www.openproject.org/news/65-api-v1-and-api-v2-deprecated-v3-in-development) for more information on that. - -# General Information - -## Authentication - -The API supports both *basic auth* and authentication via an *API access key*. The latter is transmitted either as one of the parameters, named `key`, for a request or in the request header `X-OpenProject-API-Key`. -You can find a user's API key on their account page (/my/account). - -Authentication by basic auth is enabled by default, but can be disabled in the configuration (Set apiv2_enable_basic_auth to false) - -Example request: - -_GET_ `/api/v2/projects.xml?key=gh3g4h124grr871r8g` - -## Formats - -All actions support two formats: - -* XML (`application/xml`) -* JSON (`application/json`) - -The value in parenthesis is the `Content-Type` for the respective format to be transmitted when writing data (_POST_, _PUT_). -This header has to be transmitted even though the format is already indicated by the URL, e.g. when it ends with `.xml`. - -## Terminology - -What is referred to as _planning elements_ within the API (v2) is actually a _work package_ as far as the web interface is concerned. In previous versions the same thing may have been referred to as _issues_. - -## Placeholders - -In the rest of this document the string @:format@ will be used in URLs as a placeholder for an arbitrary format chosen from the available formats given above. I.e. you can substitute either `xml` or `json` for any occurrence of `:format`. - -There is another placeholder called `:project_id`. This can either be substituted with a project's ID within the database or a project's _identifier_. -Furthermore the placeholder `:planning_element_id` has to be substituted with a planning element's ID within the database. - -*Examples:* - -The URL @/api/v2/projects/:project_id/edit@ can become: - -* `/api/v2/projects/2/edit` -* `/api/v2/projects/maintenance/edit` - -# API - -__Be aware__ This section may be incomplete. Only _planning elements_ and _custom fields_ are described at the moment and even those sections may not be complete. - -## Planning Elements - -### Index (all) - -_GET_ `/api/v2/projects/:project_id/planning_elements.:format` - -Shows **all** _planning elements_ of a given _project_. For each _planning element_ a subset of the available information will be listed. - -Example XML response excerpt: - -```xml - - - - 2 - magni sint culpa - - - - -``` - -### Index (filtered) - -*TODO: Explain that _:project_id_ can in fact be a set of projects, identifiers or ids, that are comma-separated in the URL.* - -Planning Elements can also be filtered using Query strings that correspond to work package filters. It is possible to filter on several conditions that are combined with logical AND. The following is an example filtering planning elements on `status_id`. - -_GET_ `/api/v2/projects/:project_id/planning_elements.:format?f[]=status_id&op[status_id]=%3D&v[status_id][]=5` - -The above query string corresponds to the following key-value pairs: - -``` -f[] => status_id -op[status_id] => = -v[status_id][] => 5 -``` - -* The first key, `f[]`, defines a list of fields that are being filtered. In this example, we only filter for `status_id`. -* The `op[*]` keys define the operator for each field that is being filtered. The operator used here is the equal operator, which specifies that the `status_id` of the planning elements must be equal to one of the values provided. -* The `v[*][]` key defines the values on the right side of the operation. Here, the id 5 is provided, which results in the following combined statement: - -The _status_id_ needs to _equal_ _5_. - -The following constitutes a more complex query, combining two filters, one of which is an OR-combination of values: - -_GET_ -`/api/v2/projects/seeded_project,2/planning_elements.json?f[]=type_id&op[type_id]=%3D&v[type_id][]=3&f[]=status_id&op[status_id]=%3D&v[status_id][]=5&v[status_id][]=2` - -The above query string corresponds to the following key-value pairs: - -``` -f[] => type_id -op[type_id] => = -v[type_id][] => 3 -f[] => status_id -op[status_id] => = -v[status_id][] => 5 -v[status_id][] => 2 -``` - -* The @f[]@ key is being set twice, which is being interpreted as an array of @[type_id, status_id]@ being assigned to @f[]@. -* The operatorts are subsequently set to the equal operator. Both @op[type_id]@ as well as @op[status_id]@ are set to @=@. -* The value field @v[type_id][]@ is set to 3. The value field @v[status_id][]@ is set twice, and like @f[]@, results in the array @[5, 2]@ being assigned as possible values. This results in the following combined statement: - -The _type_id_ needs to _equal_ _3_ AND the _status_id_ needs to _equal_ either _5_ OR _2_. - -The available operators can be found in the ""@Queries::Filter@"":https://github.com/opf/openproject/blob/dev/app/models/queries/filter.rb#L41-L74 class. Some of the available field options can be found in the ""@Queries::WorkPackages::AvailableFilterOptions@"":https://github.com/opf/openproject/blob/dev/app/models/queries/work_packages/available_filter_options.rb#L45-L56 class. The response when filtering planning elements is of the exact same structure than the unfiltered index action: - -``` - - - - 2 - magni sint culpa - - - - -``` - -There is a caveat when filtering trees of planning elements. When there are parent_ids in planning elements that correspond to planning elements that have been filtered out, i.e. the filter removes the parent of a planning element, then the parent_id of the planning elements is adjusted to the closest ancestor that is not filtered out. This could cause confusion when updating planning elements to the values that the server sent from a filtered query. The response to a filter can and occasionally will have objectively wrong parent_ids in favour of a reconstructable tree on the client side. - -### Show - -_GET_ @/api/v2/projects/:project_id/planning_elements/:planning_element_id.:format@ - -Shows a single planning element. The shown attributes include a list named @custom_fields@ -which shows all _custom field values_ for that particular planning element. -Each _custom field value_ entry contains at least the name of the _custom field_ and its value for this _planning element_. - -A possible response in XML could look like this: - -``` - - - - 723 - aperiam est mollitia - Via venustas peccatus. - 1 - - 3 - 3 - 2013-11-03 - 2014-02-14 - 2013-10-18T09:35:48Z - 2013-10-18T09:35:48Z - true - - - - ad ut - 1 - - - - qui enim - 2 - - - - reiciendis qui - 3 - - - - 1 - seeded_project - Seeded Project - - - 3 - Feature - - - 3 - Resolved - - -``` - -### Update - -_PUT_ @/api/v2/projects/:project_id/planning_elements/:planning_element_id.:format@ - -Updates a _planning element_. In addition to the usual attributes you can of course also update its _custom field values_. The request body for that in XML could look like this: - -``` - - - Bug in front page - - - 4 - pending - - - -``` - -Similarly when using JSON it would look like this: - -``` -{ - ""planning_element"": { - ""custom_fields"": [ - { - ""id"": 4, - ""value"": ""pending"" - } - ], - ""subject"": ""Bug in front page"" - } -} -``` - -Those requests would set a _planning element's_ subject to ""Bug in front page"" and the value for the _custom field_ with the ID 4 to 'pending'. -A _custom field's_ ID can be found out by querying the available _custom fields_ as described in the _Custom Fields_ section. -You can find out about possible _planning element_ fields by querying a projects _planning elements_ which is described in the _Show_ section. - -### Create - -_POST_ @/api/v2/projects/:project_id/planning_elements.:format@ - -The request body is exactly the same as in the _Update_ operation. -Upon successful creation the response will be a redirect to the created _planning element_, -i.e. the URL to the new _planning element_ will be sent in the @Location@ header. - -## Planning Element Journals - -*This API endpoint is broken!* _Do not try to use it!_ - -## Planning Element Priorities - -### Index - -_GET_ @/api/v2/planning_element_priorities(.:format) - -#### JSON - -``` -{ - ""planning_element_priorities"":[ - { - ""id"":10,""name"":""Wichtig"", ""position"":1,""is_default"":false - }, - { - ""id"":11,""name"":""Normal"",""position"":2,""is_default"":true - }, - { - ""id"":13,""name"":""Niedrig"",""position"":3,""is_default"":false - } - ] -} -``` - -#### XML - -``` - - - - 10 - Wichtig - 1 - false - - - 11 - Normal - 2 - true - - - 13 - Niedrig - 3 - false - - -``` - -## Custom Fields - -This section describes all actions for _custom fields_ themselves, i.e. their definitions. - -### Query Custom Fields - -_GET_ @/api/v2/custom_fields.:format@ - -Returns the definitions for all custom fields visible to the user performing the query. -Example response: - -``` - - - - 7 - sausage - list - - 0 - 0 - false - false - true - true - 7 - true - true - planning_element - - - Wiener - - - Frankfurter - - - Thüringer - - - Berner - - - Curry - - - - - 1 - none - - - 2 - Bug - - - 3 - Feature - - - 4 - Support - - - 5 - Phase - - - 6 - Milestone - - - - - - 8 - nonsense - string - .* - 0 - 0 - false - false - false - false - 1 - true - true - project - - -``` - -### Query Planning Element Custom Fields - -_GET_ @/api/v2/projects/:project_id/planning_element_custom_fields.:format@ - -Returns only the definitions of the custom fields which are enabled for a specific project. - -## Planning Element Type Colors - -### Index - -_GET_ @/api/v2/colors.:format@ - -Shows all colors for the OpenProject instance. Returns the following structure: - -``` - - - - 1 - pjBlack - 1 - #000000 - 2013-11-20T10:00:58Z - 2013-11-20T10:00:58Z - - - 2 - pjRed - 2 - #FF0013 - 2013-11-20T10:00:58Z - 2013-11-20T10:00:58Z - - [...] - -``` - -The equivalent JSON: - -``` -{ - ""colors"": [ - { - ""created_at"": ""2013-11-20T10:00:58Z"", - ""hexcode"": ""#000000"", - ""id"": 1, - ""name"": ""pjBlack"", - ""position"": 1, - ""updated_at"": ""2013-11-20T10:00:58Z"" - }, - { - ""created_at"": ""2013-11-20T10:00:58Z"", - ""hexcode"": ""#FF0013"", - ""id"": 2, - ""name"": ""pjRed"", - ""position"": 2, - ""updated_at"": ""2013-11-20T10:00:58Z"" - } - ] -} -``` - -### Show - -_GET_ @/api/v2/colors/:color_id.:format@ - -``` - - - 1 - pjBlack - 1 - #000000 - 2013-11-20T10:00:58Z - 2013-11-20T10:00:58Z - -``` - -The corresponding JSON: - -``` -{ - ""color"": { - ""created_at"": ""2013-11-20T10:00:58Z"", - ""hexcode"": ""#000000"", - ""id"": 1, - ""name"": ""pjBlack"", - ""position"": 1, - ""updated_at"": ""2013-11-20T10:00:58Z"" - } -} -``` - -## Planning Element Types - -### Index - -_GET_ @/api/v2/planning_element_types.:format@ - -``` - - - - - 1 - none - true - false - 0 - true - - 16 - pjSilver - #BFBFBF - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - - 2 - Bug - true - false - 1 - true - - 2 - pjRed - #FF0013 - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - - 3 - Feature - true - false - 2 - true - - 4 - pjLime - #82FFA1 - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - - 4 - Support - true - false - 3 - true - - 6 - pjBlue - #1E16F4 - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - - 5 - Phase - true - false - 4 - true - - 16 - pjSilver - #BFBFBF - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - - 6 - Milestone - true - true - 5 - is_default type=""boolean"">true - - 13 - pjPurple - #86007B - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - - -``` - -The corresponding JSON: - -``` -{ - ""planning_element_types"": [ - { - ""color"": { - ""hexcode"": ""#BFBFBF"", - ""id"": 16, - ""name"": ""pjSilver"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 1, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""none"", - ""position"": 0, - ""updated_at"": ""2013-11-20T10:00:59Z"" - }, - { - ""color"": { - ""hexcode"": ""#FF0013"", - ""id"": 2, - ""name"": ""pjRed"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 2, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""Bug"", - ""position"": 1, - ""updated_at"": ""2013-11-20T10:00:59Z"" - }, - { - ""color"": { - ""hexcode"": ""#82FFA1"", - ""id"": 4, - ""name"": ""pjLime"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 3, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""Feature"", - ""position"": 2, - ""updated_at"": ""2013-11-20T10:00:59Z"" - }, - { - ""color"": { - ""hexcode"": ""#1E16F4"", - ""id"": 6, - ""name"": ""pjBlue"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 4, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""Support"", - ""position"": 3, - ""updated_at"": ""2013-11-20T10:00:59Z"" - }, - { - ""color"": { - ""hexcode"": ""#BFBFBF"", - ""id"": 16, - ""name"": ""pjSilver"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 5, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""Phase"", - ""position"": 4, - ""updated_at"": ""2013-11-20T10:00:59Z"" - }, - { - ""color"": { - ""hexcode"": ""#86007B"", - ""id"": 13, - ""name"": ""pjPurple"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 6, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": true, - ""name"": ""Milestone"", - ""position"": 5, - ""updated_at"": ""2013-11-20T10:00:59Z"" - } - ] -} -``` - -### Show - -_GET_ @/api/v2/planning_element_types/:planning_element_type_id.:format@ - -``` - - - 1 - none - true - false - 0 - true - - 16 - pjSilver - #BFBFBF - - 2013-11-20T10:00:59Z - 2013-11-20T10:00:59Z - -``` - -The corresponding JSON: - -``` -{ - ""planning_element_type"": { - ""color"": { - ""hexcode"": ""#BFBFBF"", - ""id"": 16, - ""name"": ""pjSilver"" - }, - ""created_at"": ""2013-11-20T10:00:59Z"", - ""id"": 1, - ""in_aggregation"": true, - ""is_default"": true, - ""is_milestone"": false, - ""name"": ""none"", - ""position"": 0, - ""updated_at"": ""2013-11-20T10:00:59Z"" - } -} -``` - -## Project Types - -### Index - -_GET_ @/api/v2/project_types.:format@ - -``` - - - - 1 - Test - true - 1 - 2013-12-18T10:12:23Z - 2013-12-18T10:12:23Z - - - 2 - Default - true - 2 - 2013-12-18T10:12:40Z - 2013-12-18T10:12:40Z - - -``` - -The corresponding JSON: - -``` -{ - ""project_types"": [ - { - ""allows_association"": true, - ""created_at"": ""2013-12-18T10:12:23Z"", - ""id"": 1, - ""name"": ""Test"", - ""position"": 1, - ""updated_at"": ""2013-12-18T10:12:23Z"" - }, - { - ""allows_association"": true, - ""created_at"": ""2013-12-18T10:12:40Z"", - ""id"": 2, - ""name"": ""Default"", - ""position"": 2, - ""updated_at"": ""2013-12-18T10:12:40Z"" - } - ] -} -``` - -### Show - -_GET_ @/api/v2/project_types/:project_type_id.:format@ - -``` - - - 1 - Test - true - 1 - 2013-12-18T10:12:23Z - 2013-12-18T10:12:23Z - -``` - -The corresponding JSON: - -``` -{ - ""project_type"": { - ""allows_association"": true, - ""created_at"": ""2013-12-18T10:12:23Z"", - ""id"": 1, - ""name"": ""Test"", - ""position"": 1, - ""updated_at"": ""2013-12-18T10:12:23Z"" - } -} -``` - -## Projects - -### Index (all) - -_GET_ @/api/v2/projects.:format@ - -Shows all projects for the OpenProject instance. Returns the following structure: - - -``` - - - - 1 - Seeded Project - seeded_project - - Aut facilis sit officia quasi autem temporibus aut. Id culpa debitis non recusandae quibusdam dolor. Esse et et quaerat hic sapiente et. Voluptatem iste cupiditate consequatur eius laborum. Velit aspernatur provident est corrupti est. Consectetur error veritatis reprehenderit voluptas sint. - - - - - - 1 - 2 - 3 - 4 - 5 - 6 - - 2013-11-20T10:01:01Z - 2013-11-20T10:01:01Z - - - 2 - Test - test - - - - 1 - - 1 - 2 - 3 - 4 - 5 - 6 - - 2013-11-20T13:51:42Z - 2013-12-17T08:59:52Z - - -``` - -The equivalent JSON: - -``` -{ - ""projects"": [ - { - ""created_on"": ""2013-11-20T10:01:01Z"", - ""description"": ""Aut facilis sit officia quasi autem temporibus aut. Id culpa debitis non recusandae quibusdam dolor. Esse et et quaerat hic sapiente et. Voluptatem iste cupiditate consequatur eius laborum. Velit aspernatur provident est corrupti est. Consectetur error veritatis reprehenderit voluptas sint."", - ""id"": 1, - ""identifier"": ""seeded_project"", - ""name"": ""Seeded Project"", - ""parent_id"": null, - ""project_type_id"": null, - ""responsible_id"": null, - ""type_ids"": [ - 1, - 2, - 3, - 4, - 5, - 6 - ], - ""updated_on"": ""2013-11-20T10:01:01Z"" - }, - { - ""created_on"": ""2013-11-20T13:51:42Z"", - ""description"": """", - ""id"": 2, - ""identifier"": ""test"", - ""name"": ""Test"", - ""parent_id"": null, - ""project_type_id"": null, - ""responsible_id"": 1, - ""type_ids"": [ - 1, - 2, - 3, - 4, - 5, - 6 - ], - ""updated_on"": ""2013-12-17T08:59:52Z"" - } - ] -} -``` - -### Index (some) - - -It is possible to retrieve only a set of projects, however not dynamically filtered. To retrieve only a set of projects from the index action, it is possible to query with a list of comma-separated ids or identifiers. - -``` -http://localhost:3000/api/v2/projects.json?ids=seeded_project,2 -``` - -_GET_ @/api/v2/projects.:format?ids=:project_id@ - -Ids and identifiers can be interchanged, providing identification for a project multiple times will not trigger multiple occurances of that project in the response. -Providing only one id in the field of ids will result in only one project being returned, which is still different from the show action. - -### Show - -_GET_ @/api/v2/projects/:project_id.:format@ - -``` - - - 2 - Test - test - - - - true - true - true - - - 1 - OpenProject Admin - - 2013-11-20T13:51:42Z - 2013-12-17T08:59:52Z - - - 1 - none - false - - 16 - pjSilver - #BFBFBF - - - - 2 - Bug - false - - 2 - pjRed - #FF0013 - - - - 3 - Feature - false - - 4 - pjLime - #82FFA1 - - - - 4 - Support - false - - 6 - pjBlue - #1E16F4 - - - - 5 - Phase - false - - 16 - pjSilver - #BFBFBF - - - - 6 - Milestone - true - - 13 - pjPurple - #86007B - - - - - -``` - -The corresponding JSON: - -``` -{ - ""project"": { - ""created_on"": ""2013-11-20T13:51:42Z"", - ""custom_fields"": [], - ""description"": """", - ""id"": 2, - ""identifier"": ""test"", - ""name"": ""Test"", - ""permissions"": { - ""delete_planning_elements"": true, - ""edit_planning_elements"": true, - ""view_planning_elements"": true - }, - ""project_type_id"": null, - ""responsible"": { - ""id"": 1, - ""name"": ""OpenProject Admin"" - }, - ""types"": [ - { - ""color"": { - ""hexcode"": ""#BFBFBF"", - ""id"": 16, - ""name"": ""pjSilver"" - }, - ""id"": 1, - ""is_milestone"": false, - ""name"": ""none"" - }, - { - ""color"": { - ""hexcode"": ""#FF0013"", - ""id"": 2, - ""name"": ""pjRed"" - }, - ""id"": 2, - ""is_milestone"": false, - ""name"": ""Bug"" - }, - { - ""color"": { - ""hexcode"": ""#82FFA1"", - ""id"": 4, - ""name"": ""pjLime"" - }, - ""id"": 3, - ""is_milestone"": false, - ""name"": ""Feature"" - }, - { - ""color"": { - ""hexcode"": ""#1E16F4"", - ""id"": 6, - ""name"": ""pjBlue"" - }, - ""id"": 4, - ""is_milestone"": false, - ""name"": ""Support"" - }, - { - ""color"": { - ""hexcode"": ""#BFBFBF"", - ""id"": 16, - ""name"": ""pjSilver"" - }, - ""id"": 5, - ""is_milestone"": false, - ""name"": ""Phase"" - }, - { - ""color"": { - ""hexcode"": ""#86007B"", - ""id"": 13, - ""name"": ""pjPurple"" - }, - ""id"": 6, - ""is_milestone"": true, - ""name"": ""Milestone"" - } - ], - ""updated_on"": ""2013-12-17T08:59:52Z"" - } -} -``` - -## Reportings - -When calling the index action it is possible to scope the reportings that ought to be retrieved to @via_target@, @via_source@, or not at all. -* *@via_target@* will only regard reportings that _report into the project that the reportings are retrieved from_. -* *@via_source@* will only regard reportings that _the project that the reportings are retrieved from reports into_. -* *No scoping* will result in all reportings being regarded that _the project the reportings are retrieved from is involved in_. - -### Index (all) - -_GET_ @/api/v2/projects/:project_id/reportings.:format@ - -``` - - - - 1 - - 13 - Green - - - 2013-11-21T13:10:56Z - 2013-12-18T10:22:20Z - - 1 - seeded_project - Seeded Project - - - 2 - test - Test - - - -``` - -The corresponding JSON: - -``` -{ - ""reportings"": [ - { - ""created_at"": ""2013-11-21T13:10:56Z"", - ""id"": 1, - ""project"": { - ""id"": 2, - ""identifier"": ""test"", - ""name"": ""Test"" - }, - ""reported_project_status"": { - ""id"": 13, - ""name"": ""Green"" - }, - ""reported_project_status_comment"": """", - ""reporting_to_project"": { - ""id"": 1, - ""identifier"": ""seeded_project"", - ""name"": ""Seeded Project"" - }, - ""updated_at"": ""2013-12-18T10:22:20Z"" - } - ] -} -``` - -### Index (filtered) - -Reportings can also be filtered based on the projects involved. One of the involved projects needs to conform to the specified query parameters. Reportings filters support: - -* Project types via the @project_types@ field. -* Project status via the @project_statuses@ field. -* Responsible via the @project_responsibles@ field. - -_GET_ @/api/v2/projects/:project_id/reportings.:format?only=via_target&project_types=2&project_statuses=13&project_responsibles=-1,1@ - -The above query string corresponds to the following key-value pairs: - -``` -only => via_target -project_types => 2 -project_statuses => 13 -project_responsibles => -1,1 -``` - -The values can be comma-separated lists of ids. A _-1_ value in the list stands for the _(none)_ value, i.e. the field is allowed not to be set (nil). It is also possible to filter for timelines first level grouping criteria as well as project parents in general. The relevant filters can be found in ""Api::V2::ReportingsController"":https://github.com/opf/openproject/blob/dev/app/controllers/api/v2/reportings_controller.rb#L95-L165. - -## Project Associations - -*This API endpoint is deprecated!* _Don't use it!_ - -### Available Project - -_GET_ @/api/v2/projects/:project_id/project_associations/available_projects.:format@ - -### Index - -_GET_ @/api/v2/projects/:project_id/project_associations/.:format@ - -### Create - -_POST_ @/api/v2/projects/:project_id/project_associations/.:format@ - -### New - -_GET_ @/api/v2/projects/:project_id/project_associations/new.:format@ - -### Edit - -_GET_ @/api/v2/projects/:project_id/project_associations/:id/edit.:format@ - -### Show - -_GET_ @/api/v2/projects/:project_id/project_associations/:id.:format@ - -### Update - -_PUT_ @/api/v2/projects/:project_id/project_associations/:id.:format@ - -### Destroy - -_POST_ @/api/v2/projects/:project_id/project_associations/:id.:format@ - -## Statuses - -### Index - -_GET_ @/api/v2/statuses.:format@ - -``` - - - - 1 - New - 1 - true - false - - - - 3 - Resolved - 3 - false - false - - - - 4 - Feedback - 4 - false - false - - - - 5 - Closed - 5 - false - true - - - - 2 - In Progress - 7 - false - false - - - - 6 - Rejected - 6 - false - true - - - -``` - -The corresponding JSON: - -``` -{ - ""statuses"": [ - { - ""default_done_ratio"": null, - ""id"": 1, - ""is_closed"": false, - ""is_default"": true, - ""name"": ""New"", - ""position"": 1 - }, - { - ""default_done_ratio"": null, - ""id"": 3, - ""is_closed"": false, - ""is_default"": false, - ""name"": ""Resolved"", - ""position"": 3 - }, - { - ""default_done_ratio"": null, - ""id"": 4, - ""is_closed"": false, - ""is_default"": false, - ""name"": ""Feedback"", - ""position"": 4 - }, - { - ""default_done_ratio"": null, - ""id"": 5, - ""is_closed"": true, - ""is_default"": false, - ""name"": ""Closed"", - ""position"": 5 - }, - { - ""default_done_ratio"": null, - ""id"": 2, - ""is_closed"": false, - ""is_default"": false, - ""name"": ""In Progress"", - ""position"": 7 - }, - { - ""default_done_ratio"": null, - ""id"": 6, - ""is_closed"": true, - ""is_default"": false, - ""name"": ""Rejected"", - ""position"": 6 - } - ] -} -``` - -### Show - -_GET_ @/api/v2/statuses/:status_id.:format@ - -``` - - - 1 - New - 1 - true - false - - -``` - -The corresponding JSON: - -``` -{ - ""status"": { - ""default_done_ratio"": null, - ""id"": 1, - ""is_closed"": false, - ""is_default"": true, - ""name"": ""New"", - ""position"": 1 - } -} -``` - -## Users - -### Index (some) - -Users can not be indexed w/o specific ids. To retrieve some users, their ids must be provided in the query string as a comma seperated list. - -It is possible that users that exist will not be returned when their id is provided. Only users that stisfy the visibility condition will be returned, all other users will be omitted in the result. The visible condition is defined in the ""@Principal@"":https://github.com/opf/openproject/blob/dev/app/models/principal.rb#L87-L95 class. - -_GET_ @/api/v2/users.:format?ids=:user_ids@ - -``` - - - - 1 - OpenProject - Admin - OpenProject Admin - - -``` - -The corresponding JSON: - -``` -{ - ""users"": [ - { - ""firstname"": ""OpenProject"", - ""id"": 1, - ""lastname"": ""Admin"", - ""name"": ""OpenProject Admin"" - } - ] -} -``` - -## Workflows - -### Index - -* Related Tickets -** #3113 - -A list of workflows is a list of ""type"":https://www.openproject.org/projects/openproject/wiki/API_v2/#14-Planning-Element-Types / ""status"":https://www.openproject.org/projects/openproject/wiki/API_v2/#18-Statuses pairs and their respective transitions. Transitions are ""status"":https://www.openproject.org/projects/openproject/wiki/API_v2/#18-Statuses / scope pairs. - -A scope can have one of three values role|author|assignee. Thus, if atransition has the scope author, only a user who is author of the respective ticket may be allowed to use this transition. The same is valid for assignee. The scope role is valid in the cases where the user is neither author or assignee. - -_GET_ @/api/v2/projects/:project_id/workflows(.:format)@ - -#### JSON - -``` -{""workflows"": - [ - {""type_id"":1, - ""old_status_id"":2, - ""transitions"":[ - {""new_status_id"":3,""scope"":""author""}, - {""new_status_id"":14,""scope"":""role""}, - {""new_status_id"":13,""scope"":""role""} - ]} - ]} -``` - -#### XML - -``` - - - 1 - 2 - - - 3 - author - - - 14 - role - - - 13 - role - - - -``` - -## Authentication - -### Index - -* Related Tickets -** #4163 - -This end-point returns the following HTTP status codes: - -| *HTTP Status Code* | *Meaning* | *Response* | -| ------------------ | --------- | ---------------------------------------------------- | -| 200 | Success | Authentication Data | -| 401 | Unauthorized - cannot find user for given credentials | empty | -| 403 | Forbidden - API does not allow authentication (Settings) | empty | - -If the authentication is successful, the API returns data that contains the OpenProject user id for the authenticated user. - -_GET_ @/api/v2/authentication(.:format)@ - -#### JSON - -``` -{ - ""authorization"": - { - ""authorized"":true, - ""authenticated_user_id"":96 - } -} -``` - -#### XML - -``` - - true - 96 - -``` - - -# Examples - -Here are few example requests made using _curl_ are shown: - -## Creating a Planning Element (w/ authentication) - -Request: - -```bash -curl -u admin:admin -X POST --header ""Content-Type: application/json"" -d '{""planning_element"": {""subject"": ""Test Issue"", ""status_id"": 1 /* new */, ""type_id"": 3 /* Feature */}' http://localhost:3000/api/v2/projects/seeded_project/planning_elements.json -``` - -Response: - -```html - - - You are being redirected. - - -`` - diff --git a/doc/subversion_and_git_integration.md b/doc/subversion_and_git_integration.md deleted file mode 100644 index 411af2d7d6f..00000000000 --- a/doc/subversion_and_git_integration.md +++ /dev/null @@ -1,9 +0,0 @@ -# Subversion and Git 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. - --- - -The repositories integration guide for OpenProject 5.0 has been moved [here](./operation_guides/manual/repository-integration.md). -If you're looking for upgrading existing repository functionality (e.g., the reposman.rb cron job) to OpenProject 5.0, follow the repository section of [the upgrade guide](./operation_guides/manual/upgrade-guide.md). \ No newline at end of file diff --git a/doc/wp/backup/backup-guide.md b/doc/wp/backup/backup-guide.md new file mode 100644 index 00000000000..39d6b878263 --- /dev/null +++ b/doc/wp/backup/backup-guide.md @@ -0,0 +1,71 @@ +# Backup your OpenProject installation + +**Note:** this guide only applies if you've installed OpenProject using our DEB/RPM +packages. + +We advise to backup your OpenProject installation regularly — especially before +upgrading to a newer version. + +## What should be backed up + +In general the following parts of your OpenProject installation should be backed up: + +* Data stored in the database +* Configuration files +* Uploaded files (attachments) +* Repositories (typically subversion) if applicable + +## How to backup + +The DEB/RPM packages provide a backup tool which can be used to take a snaphsot +of the current OpenProject installation. This tool will create a backup of +all parts mentioned above. The backup tool is used by executing the following +command: + + sudo openproject run backup + +The command will create backup files in the following location on your system + + /var/db/openproject/backup + +The content of that directory should look very similar to the following: + +```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/wp/installation/0-preparation.md b/doc/wp/installation/0-preparation.md new file mode 100644 index 00000000000..060afa737b7 --- /dev/null +++ b/doc/wp/installation/0-preparation.md @@ -0,0 +1,30 @@ + +We strongly suggest installing OpenProject using our RPM/Deb packages. +The packages provide a fast and reliable method to get started with OpenProject, as well as upgrading your installation to the latest version. + +The package contains an interactive wizard that will configure your environment with all necessary dependencies (Ruby, Node, database setup, Apache setup, and integrations with OpenpProject). + + +# OpenProject Packaged Installation Guide + +The installation procedure assumes the following prerequisites: + +* A server running one of the Linux distributions listed in the [system requirements](./system-requirements.md). +* A mail server that is accessible via SMTP that can be used for sending + notification emails. +* 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 package will set up: + +* 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.2 (MRI) and necessary libraries to run the OpenProject source code. + diff --git a/doc/wp/installation/1-installation.md b/doc/wp/installation/1-installation.md new file mode 100644 index 00000000000..c24fca28ec4 --- /dev/null +++ b/doc/wp/installation/1-installation.md @@ -0,0 +1,3 @@ +## Install package + +To install the package, you need to add the packager.io package source to your distribution package manager. \ No newline at end of file diff --git a/doc/wp/installation/2-configuration.md b/doc/wp/installation/2-configuration.md new file mode 100644 index 00000000000..dae4a24c83f --- /dev/null +++ b/doc/wp/installation/2-configuration.md @@ -0,0 +1,124 @@ + +# Package configuration + +The last step to your OpenProject installation is the configuration wizard. It will set up the connection to a database and configure the application according to your environment. + +The OpenProject installation wizard currently supports the automatic setup 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 diff --git a/doc/wp/installation/3-customization.md b/doc/wp/installation/3-customization.md new file mode 100644 index 00000000000..8fceee1354b --- /dev/null +++ b/doc/wp/installation/3-customization.md @@ -0,0 +1,52 @@ +# Customization: Installing Plugins + +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/wp/installation/alternative-methods.md b/doc/wp/installation/alternative-methods.md new file mode 100644 index 00000000000..290fc5d6bea --- /dev/null +++ b/doc/wp/installation/alternative-methods.md @@ -0,0 +1,3 @@ +# Alternative Installation Methods + +If you cannot use our packaged installation, you can see our [community contributed user guides](https://github.com/opf/openproject/tree/dev/guides/installing) for alternative installation methods. \ No newline at end of file diff --git a/doc/wp/installation/centos-7/steps.md b/doc/wp/installation/centos-7/steps.md new file mode 100644 index 00000000000..0069d645e49 --- /dev/null +++ b/doc/wp/installation/centos-7/steps.md @@ -0,0 +1,31 @@ +Steps to install the OpenProject package for Debian 7 (Wheezy). +All steps are run with `sudo` to execute as the root user. + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +sudo rpm --import https://rpm.packager.io/key +``` + +**2. Add the OpenProject package source** + +Create the file `/etc/yum.repos.d/openproject.repo` with the following contents + + +``` +[openproject] +name=Repository for opf/openproject-ce application. +baseurl=https://rpm.packager.io/gh/opf/openproject-ce/centos7/stable/6 +enabled=1 +``` + + +**3. Install the OpenProject Community Edition package** + +Using the following command, yum will install the package and all required dependencies. + +```bash +sudo yum install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/debian-7/steps.md b/doc/wp/installation/debian-7/steps.md new file mode 100644 index 00000000000..7972eb36638 --- /dev/null +++ b/doc/wp/installation/debian-7/steps.md @@ -0,0 +1,38 @@ +Steps to install the OpenProject package for Debian 7 (Wheezy). +All steps need to be run as `root`. + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget -qO - https://deb.packager.io/key | sudo apt-key add - +``` + +**2. Install apt-https suppport** + +Since we only provide https package sources, you may need to install `apt-transport-https` as a preliminary step. + +```bash +apt-get install apt-transport-https +``` + + +**3. Add the OpenProject package source** + +Create the file `/etc/apt/sources.list.d/openproject.list` with the following contents + + +``` +deb https://deb.packager.io/gh/opf/openproject-ce wheezy stable/6 +``` + + +**4. Install the OpenProject Community Edition package** + +Using the following commands, apt will check the new package source and install the package and all required dependencies. + +```bash +apt-get update +apt-get install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/debian-8/steps.md b/doc/wp/installation/debian-8/steps.md new file mode 100644 index 00000000000..b1496ce70ff --- /dev/null +++ b/doc/wp/installation/debian-8/steps.md @@ -0,0 +1,38 @@ +Steps to install the OpenProject package for Debian 8 (Jessie). +All steps need to be run as `root`. + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget -qO - https://deb.packager.io/key | sudo apt-key add - +``` + +**2. Install apt-https suppport** + +Since we only provide https package sources, you may need to install `apt-transport-https` as a preliminary step. + +```bash +apt-get install apt-transport-https +``` + + +**3. Add the OpenProject package source** + +Create the file `/etc/apt/sources.list.d/openproject.list` with the following contents + + +``` +deb https://deb.packager.io/gh/opf/openproject-ce jessie stable/6 +``` + + +**4. Install the OpenProject Community Edition package** + +Using the following commands, apt will check the new package source and install the package and all required dependencies. + +```bash +apt-get update +apt-get install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/sles-11/steps.md b/doc/wp/installation/sles-11/steps.md new file mode 100644 index 00000000000..4e5167ef645 --- /dev/null +++ b/doc/wp/installation/sles-11/steps.md @@ -0,0 +1,30 @@ +Steps to install the OpenProject package for Suse Linux Enterprise Server 11. All steps need to be run as `root`. + + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget https://rpm.packager.io/key -O packager.key +rpm --import packager.key +``` + +**2. Add the OpenProject package source** + +Add a named zypper repository source for OpenProject using the following commands: + +``` +zypper addrepo "https://rpm.packager.io/gh/opf/openproject-ce/sles11/stable/6" "openproject" +``` + +The package source is now registered as `openproject`. + + +**3. Install the OpenProject Community Edition package** + +Using the following command, zypper will install the package and all required dependencies. + +```bash +zypper install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/sles-12/steps.md b/doc/wp/installation/sles-12/steps.md new file mode 100644 index 00000000000..15ee25b9635 --- /dev/null +++ b/doc/wp/installation/sles-12/steps.md @@ -0,0 +1,30 @@ +Steps to install the OpenProject package for Suse Linux Enterprise Server 12. All steps need to be run as `root`. + + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget https://rpm.packager.io/key -O packager.key +rpm --import packager.key +``` + +**2. Add the OpenProject package source** + +Add a named zypper repository source for OpenProject using the following commands: + +``` +zypper addrepo "https://rpm.packager.io/gh/opf/openproject-ce/sles12/stable/6" "openproject" +``` + +The package source is now registered as `openproject`. + + +**3. Install the OpenProject Community Edition package** + +Using the following command, zypper will install the package and all required dependencies. + +```bash +zypper install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/ubuntu-14.04/steps.md b/doc/wp/installation/ubuntu-14.04/steps.md new file mode 100644 index 00000000000..3ddc7c2f6c2 --- /dev/null +++ b/doc/wp/installation/ubuntu-14.04/steps.md @@ -0,0 +1,29 @@ +Steps to install the OpenProject package for Ubuntu 14.04 Trusty. +All steps are prepended with `sudo` to ensure execution as the root user. + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget -qO - https://deb.packager.io/key | sudo apt-key add - +``` + +**2. Add the OpenProject package source** + +Create the file `/etc/apt/sources.list.d/openproject.list` with the following contents + + +``` +deb https://deb.packager.io/gh/opf/openproject-ce trusty stable/6 +``` + + +**3. Install the OpenProject Community Edition package** + +Using the following commands, apt will check the new package source and install the package and all required dependencies. + +```bash +apt-get update +apt-get install openproject +``` \ No newline at end of file diff --git a/doc/wp/installation/ubuntu-16.04/steps.md b/doc/wp/installation/ubuntu-16.04/steps.md new file mode 100644 index 00000000000..5300aa4e18f --- /dev/null +++ b/doc/wp/installation/ubuntu-16.04/steps.md @@ -0,0 +1,29 @@ +Steps to install the OpenProject package for Ubuntu 16.04 Xenial. +All steps are prepended with `sudo` to ensure execution as the root user. + +**1. Import the packager.io repository signing key** + +Import the PGP key used to sign our packages. Since we're using the _packager.io_ platform to distribute our packages, both package source and signing key are tied to their service. + +```bash +wget -qO - https://deb.packager.io/key | sudo apt-key add - +``` + +**2. Add the OpenProject package source** + +Create the file `/etc/apt/sources.list.d/openproject.list` with the following contents + + +``` +deb https://deb.packager.io/gh/opf/openproject-ce xenial stable/6 +``` + + +**3. Install the OpenProject Community Edition package** + +Using the following commands, apt will check the new package source and install the package and all required dependencies. + +```bash +apt-get update +apt-get install openproject +``` \ No newline at end of file diff --git a/doc/wp/system_requirements.md b/doc/wp/system_requirements.md new file mode 100644 index 00000000000..92dee769710 --- /dev/null +++ b/doc/wp/system_requirements.md @@ -0,0 +1,52 @@ +# System Requirements + +__Note__: The configurations described below are what we use and test against. +This means that other configurations might also work but we do not +provide any official support for them. + +## Server + +### Hardware + +* __Memory:__ 512 MB (1024 recommended) +* __Free disc space:__ 300 MB (4096 recommended) + +### Operating System + +| Distribution (64 bits only) | Identifier | init system | +| :------------------------------ | :----------- | :---------- | +| CentOS/RHEL 7.x | centos-7 | systemd | +| Debian 7 Wheezy | debian-7 | sysvinit | +| Debian 8 Jessie | debian-8 | systemd | +| Suse Linux Enterprise Server 11 | sles-11 | sysvinit | +| Suse Linux Enterprise Server 12 | sles-12 | sysvinit | +| Ubuntu 14.04 Trusty Tahr | ubuntu-14.04 | upstart | +| Ubuntu 16.04 Xenial Xerus | ubuntu-16.04 | upstart | + + +### Dependencies + +* __Runtime:__ [Ruby](https://www.ruby-lang.org/en/) Version >= 2.2.5, < 2.4 +* __Webserver:__ [Apache](http://httpd.apache.org/) + or [nginx](http://nginx.org/en/docs/) +* __Application server:__ [Phusion Passenger](https://www.phusionpassenger.com/) + or [Unicorn](http://unicorn.bogomips.org/) +* __Database:__ [MySQL](https://www.mysql.com/) Version >= 5.6 + or [PostgreSQL](http://www.postgresql.org/) Version >= 9.1 + +Please be aware that the dependencies listed above also have a lot of +dependencies themselves. + +## Client + +OpenProject supports the latest versions of the major browsers. In our +strive to make OpenProject easy and fun to use we had to drop support +for some older browsers. + +* [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/products/) (Version >= 45 ESR) +* [Microsoft Egde](https://www.microsoft.com/de-de/windows/microsoft-edge) +* [Google Chrome](https://www.google.com/chrome/browser/desktop/) + +## Screen reader support (accessibility) + +* [JAWS](http://www.freedomscientific.com/Products/Blindness/JAWS) >= 17.0 diff --git a/doc/wp/upgrading/upgrade-guide-legacy.md b/doc/wp/upgrading/upgrade-guide-legacy.md new file mode 100644 index 00000000000..7b8046df7cb --- /dev/null +++ b/doc/wp/upgrading/upgrade-guide-legacy.md @@ -0,0 +1,170 @@ +# 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/wp/upgrading/upgrade-guide.md b/doc/wp/upgrading/upgrade-guide.md new file mode 100644 index 00000000000..6293dc1715c --- /dev/null +++ b/doc/wp/upgrading/upgrade-guide.md @@ -0,0 +1,55 @@ +# Upgrading your OpenProject installation + +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/guides/README.md b/guides/README.md new file mode 100644 index 00000000000..f41ba213ae9 --- /dev/null +++ b/guides/README.md @@ -0,0 +1,38 @@ +# OpenProject Community Guides + + +## Installation + +Get started with installing and upgrading OpenProject using [our Installation Guide starting point](https://www.openproject.org/open-source/download/). + +The guides for manual and Docker-based installations [are located here](./installing/README.md). + +## Upgrading + +The detailed upgrade instructions for our packaged installer are located on the [official website](https://www.openproject.org/download/upgrade-guides/). + +The guides for manual and Docker-based installations [are located here](./upgrading/README.md). + +## Operation + +* [Backup guide](./backup/README.md) +* [Alter configuration of OpenProject](./configuration/README.md) +* [Manual repository integration for Git and Subversion](./repositories/README.md) +* [Configure incoming mails](./incoming-mails/README.md) +* [Install custom plugins](./plugins/README.md) + + +## User Guides + +Please see our [User Guide pages](https://www.openproject.org/help/user-guides/) for detailed documentation on the functionality of OpenProject. + + +## Development + +* [Quick Start for developers](./development/quick-start.md) +* [Full development environment for developers](./development/setting-up-development-environment.md) +* [Developing plugins](./development/create-openproject-plugin.md) +* [Developing OmniAuth Plugins](./development/create-omniauth-plugin.md) +* [Running tests](./development/running-tests.md) +* [Code review guidelines](./development/code-review-guidelines.md) +* [API documentation](./api/README.md) \ No newline at end of file diff --git a/guides/api/README.md b/guides/api/README.md new file mode 100644 index 00000000000..4134e5b810e --- /dev/null +++ b/guides/api/README.md @@ -0,0 +1,18 @@ +API Documentation +----------------- + +## API Version 3 + +_Status: under development_ + +The documentation for APIv3 is written in the [API Blueprint Format](http://apiblueprint.org/). + +The generated APIv3 documentation is built regular on the `dev` branch and can be found at: [opf.github.io/apiv3-doc/](opf.github.io/apiv3-doc/). + + +You can also use [aglio](https://github.com/danielgtaylor/aglio) to generate HTML documentation locally, e.g. using the following command: + +```bash +aglio -i apiv3-documentation.apib -o api.html +``` + diff --git a/guides/backup/README.md b/guides/backup/README.md new file mode 100644 index 00000000000..ec9304babf0 --- /dev/null +++ b/guides/backup/README.md @@ -0,0 +1,12 @@ +# Packaged installation Backup Guide + +The detailed backup instructions for our packages are located on the [official website](https://www.openproject.org/open-source/upgrade-backup/). + + +# Manual installation + +The backup guide for your manual installation [can be found here](./manual/README.md). + +# Docker installation + +The backup guide for your Docker-based installation [can be found here](./docker/README.md). \ No newline at end of file diff --git a/guides/backup/docker/README.md b/guides/backup/docker/README.md new file mode 100644 index 00000000000..c9c8f5134d9 --- /dev/null +++ b/guides/backup/docker/README.md @@ -0,0 +1,24 @@ +# 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/guides/backup/manual/README.md b/guides/backup/manual/README.md new file mode 100644 index 00000000000..1bcc9e7ef1f --- /dev/null +++ b/guides/backup/manual/README.md @@ -0,0 +1,116 @@ +# 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/CONFIGURATION.md b/guides/configuration/README.md similarity index 90% rename from doc/CONFIGURATION.md rename to guides/configuration/README.md index 8691ab20020..81f5656617e 100644 --- a/doc/CONFIGURATION.md +++ b/guides/configuration/README.md @@ -1,32 +1,3 @@ - - # OpenProject Configuration This file describes a part of the OpenProject configuration. You can find general installation instructions [here](INSTALL.md). OpenProject also allows configuring many aspects via its admin interface. The config/settings.yml file should *not* be used for changing these settings. diff --git a/guides/development/README.md b/guides/development/README.md new file mode 100644 index 00000000000..4509e308a80 --- /dev/null +++ b/guides/development/README.md @@ -0,0 +1,7 @@ +# Resources for developers + + +* [Quick Start for Developers](development/QUICK_START.md) +* [Developing Plugins](development/create-openproject-plugin.md) +* [Running Tests](RUNNING_TESTS.md) +* [API Documentation](./api/README.md) \ No newline at end of file diff --git a/doc/code-review-guidelines.md b/guides/development/code-review-guidelines.md similarity index 100% rename from doc/code-review-guidelines.md rename to guides/development/code-review-guidelines.md diff --git a/doc/development/create-omniauth-plugin.md b/guides/development/create-omniauth-plugin.md similarity index 100% rename from doc/development/create-omniauth-plugin.md rename to guides/development/create-omniauth-plugin.md diff --git a/doc/development/create-openproject-plugin.md b/guides/development/create-openproject-plugin.md similarity index 100% rename from doc/development/create-openproject-plugin.md rename to guides/development/create-openproject-plugin.md diff --git a/doc/QUICK_START.md b/guides/development/quick-start.md similarity index 76% rename from doc/QUICK_START.md rename to guides/development/quick-start.md index e348400a39c..1afdc997556 100644 --- a/doc/QUICK_START.md +++ b/guides/development/quick-start.md @@ -1,32 +1,3 @@ - - # Quick Start for Developers diff --git a/doc/RUNNING_TESTS.md b/guides/development/running-tests.md similarity index 94% rename from doc/RUNNING_TESTS.md rename to guides/development/running-tests.md index b9b62c3f9f6..d918b644cc7 100644 --- a/doc/RUNNING_TESTS.md +++ b/guides/development/running-tests.md @@ -225,3 +225,15 @@ on a machine with 8 parallel instances. * Sometimes you want to test things manually. Always remember: If you test something more than once, write an automated test for it. * Assuming you do not have a version of Internet Explorer already installed on your computer, you can grab a VM with preinstalled IE's directly from Microsoft: http://www.modern.ie/en-us/virtualization-tools#downloads + + +## Legacy LDAP tests + +OpenProject supports using LDAP for user authentications. To test LDAP +with OpenProject, load the LDAP export from test/fixtures/ldap/test-ldap.ldif +into a testing LDAP server. Test that the ldap server can be accessed +at 127.0.0.1 on port 389. + +Setting up the test ldap server is beyond the scope of this documentation. +The OpenLDAP project provides a simple LDAP implementation that should work +good as a test server. diff --git a/doc/development/setting-up-development-environment.md b/guides/development/setting-up-development-environment.md similarity index 100% rename from doc/development/setting-up-development-environment.md rename to guides/development/setting-up-development-environment.md diff --git a/guides/incoming-mails/README.md b/guides/incoming-mails/README.md new file mode 100644 index 00000000000..d833b16cbd2 --- /dev/null +++ b/guides/incoming-mails/README.md @@ -0,0 +1,130 @@ +# Incoming Mail Functionality + +OpenProject is able to receive emails and create and update work packages and reply in forums depending on the content of the email. + +## Setup + +Receiving emails is done via a rake task that fetches emails from an email server, parses them and performs actions depending on the content of the email. This rake task can be executed manually or automatically, e.g. with the help of a Cron job. + +### IMAP + +The rake task `redmine:email:receive_imap` fetches emails via IMAP and parses them. +Example: + +```bash +bundle exec rake redmine:email:receive_imap host='imap.gmail.com' username='test_user' password='password' port=993 ssl=true allow_override=type,project project=test_project +``` + +Available arguments for this rake task that specify the email behavior are + +|key | description| +|----|------------| +| `host` | address of the email server | +| `username` | the name of the user that is used to connect to the email server| +| `password` | the password of the user| +| `port` | the port that is used to connect to the email server| +| `ssl` | specifies if SSL should be used when connecting to the email server| +| `folder` | the folder to fetch emails from (default: INBOX)| +| `move_on_success` | the folder emails that were successfully parsed are moved to (instead of deleted)| +| `move_on_failure` | the folder emails that were ignored are moved to| + +Available arguments that change how the work packages are handled: + +| key | description | +|---|---| +| `project` | identifier of the target project | +| `tracker` | name of the target tracker | +| `category` | name of the target category | +| `priority` | name of the target priority | +| `allow_override` | specifies which attributes may be overwritten though specified by previous options. Comma separated list | + + +### POP3 + +The rake task `redmine:email:receive_pop3` fetches emails via IMAP and parses them. +Example: +```bash +bundle exec rake redmine:email:receive_pop3 host='pop.gmail.com' username='test_user' password='password' port=995 allow_override=priority +``` + +Available options that specifiy the email behavior are: + +|key | description| +|----|------------| +|`host` | address of the email server (default: 127.0.0.1)| +| username | name of the user that is used to connect to the email server| +| password | password of the user| +| port| POP3 server port (default: 110)| +| apop | use APOP authentication (default: false)| +| delete_unprocessed | delete messages that were ignored (default: leave them on the server)| + +Available arguments that change how the work packages are handled: + +|key | description| +|----|------------| +| `project` | identifier of the target project| +| `tracker` | name of the target tracker| +| `category` | name of the target category| +| `priority` | name of the target priority| +| `allow_override` | specifies which attributes may be overwritten though specified by previous options. Comma separated list| + +If you set a default value it will be used when creating a work package. + +But then no other value is possible (even when you update the work package) unless you specify this with the use of `allow_override`. Some attributes (like `type, status, priority`) are only changeable if you specify this via `allow_override`. But notice: Some attributes have to specified in another format here, e.g. Assignee can be allowed to be overriden with `allow_override=assigned_to`. + + +## Format of the Emails + +### Work Packages + +#### Sending user address + +The address the mail is sent from must match an existing account in order to map the user action. +If a matching account is found, the mail handler impersonates the user to create the ticket. + +If no matching account is found, the mail is rejected. To override this behavior and allow unknown mail address +to create work packages, set the option `no_permission_check=1`. + +**Note**: This feature only provides a mapping of mail to user account, it does not authenticate the user based on the mail. +Since you can easily spoof mail addresses, you should not rely on the authenticity of work packages created that way. + +#### Attributes + +The Attributes you can use in your email are the same whether you create or update a work package. + +Only the `project` attribute is a bit special: + +You must either add `project` to the set of allowed overridden attributes with `allow_override=project,..` in order to use it in a mail, +OR set it as fixed variable with `project=identifier`. + +The subject of the work package that shall be created is derived from the subject of the email. The body of the email gets parsed and all lines that contain recognized keys are removed. What is left will become the description. + +Other available keys for the email are: + +|Key|Description|Example| +|---|---|---| +| Project | sets the project. Use the project identifier | Project:test\_project | +| Assignee | sets the assignee. Use the email or login of the user | Assignee:test.nutzer@example.org | +| Type | sets the type | type:Milestone | +| Version | sets the version | version:v4.1.0 | +| Start date | sets the start date | start date:2015-02-28 | +| Due date | sets the due date | | +| Done ratio | sets the done ratio. Use a number | Done ratio:40 | +| Status | sets the status | Status:closed | +| priority | sets the priority | priority:High | + +If you want to set a custom field just use the name as it is displayed in your browser, e.g. `Custom field:new value` + +**Notice: The keys are not case-sensitive but the values you want to set are.** + +#### Attachments + +If you create or update a work package via email the attachments of the email will be attached to the relevant work package. + +#### Watchers + +If you create a work package via email and sent it to another email (to or bcc) OpenProject will search for a user with this email and add it as watcher. + +### Truncate Emails + +In the administator's setting you can specify lines after which an email will not be parsed anymore. That is useful if you want to reply to an email automatically sent to you from OpenProject. E.g. you could set it to `--Truncate here--` and insert this line into your email below the updates you want to perform. diff --git a/guides/installing/README.md b/guides/installing/README.md new file mode 100644 index 00000000000..192e7817e82 --- /dev/null +++ b/guides/installing/README.md @@ -0,0 +1,18 @@ +# OpenProject Installation Guides + + +## Packages + +We strongly suggest installing OpenProject using our RPM/Deb packages. +The packages provide a fast and reliable method to get started with OpenProject, as well as upgrading your installation to the latest version. + +Get started with installing and upgrading OpenProject using [our Installation Guide starting point](https://www.openproject.org/open-source/download/). + +## Docker Images + +We provide Docker images for the OpenProject Community Edition. Please see [this guide](./docker/README.md) for more information. + + +## Manual Installation + +If you prefer to set up OpenProject from source, please use the [manual installation guide](./manual/README.md) for a step-by-step guide to complete your installation. Please do note that OpenProject requires an extensive set of dependencies and we highly recommend to choose either the installation package or the docker image instead. \ No newline at end of file diff --git a/guides/installing/docker/README.md b/guides/installing/docker/README.md new file mode 100644 index 00000000000..6ac63c3aaf9 --- /dev/null +++ b/guides/installing/docker/README.md @@ -0,0 +1,150 @@ +# Install OpenProject (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/guides/installing/manual/README.md b/guides/installing/manual/README.md new file mode 100644 index 00000000000..24f92632274 --- /dev/null +++ b/guides/installing/manual/README.md @@ -0,0 +1,477 @@ +# Manual 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). + +## 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/guides/repositories/README.md b/guides/repositories/README.md new file mode 100644 index 00000000000..b97402f5798 --- /dev/null +++ b/guides/repositories/README.md @@ -0,0 +1,433 @@ +# 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/guides/upgrading/README.md b/guides/upgrading/README.md new file mode 100644 index 00000000000..bb7b7f885ad --- /dev/null +++ b/guides/upgrading/README.md @@ -0,0 +1,12 @@ +# Packaged installation Upgrade Guide + +The detailed upgrade instructions are located on the [official website](https://www.openproject.org/download/upgrade-guides/). + + +# Manual installation + +The upgrade guide for your manual installation [can be found here](./manual/README.md). + +# Docker installation + +The upgrade guide for your Docker-based installation [can be found here](./docker/README.md). \ No newline at end of file diff --git a/guides/upgrading/docker/README.md b/guides/upgrading/docker/README.md new file mode 100644 index 00000000000..aea767eeec5 --- /dev/null +++ b/guides/upgrading/docker/README.md @@ -0,0 +1,16 @@ +# 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/guides/upgrading/manual/README.md b/guides/upgrading/manual/README.md new file mode 100644 index 00000000000..ad390901d05 --- /dev/null +++ b/guides/upgrading/manual/README.md @@ -0,0 +1,239 @@ +# OpenProject 6.0.x to OpenProject 6.1 Debian/Ubuntu Upgrade Guide (Manual installation) + +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 +``` + +As a reference, the following Node.js and NPM versions have been installed on our system: + +```bash +[openproject@debian]# node --version + v0.12.2 +[openproject@debian]# npm --version + 1.4.28 +``` + +## The Upgrade + +Now that the sources and dependencies are in place, you can migrate the Database and do the upgrade. + +Before actually migrating the database, please remove all temporary files from the previous installation (caches, sessions) by running the following command. + +```bash +[openproject@debian]# cd /home/openproject/openproject +[openproject@debian]# RAILS_ENV="production" bundle exec rake tmp:clear +``` + +If you do not clear the temporary files, you may encounter an error of the form `NoMethodError: undefined method `map' for #` in the `config/initializers/30-patches.rb` files. +The actual upgrade commands are as follows: + +```bash +[openproject@debian]# cd /home/openproject/openproject +[openproject@debian]# npm install +[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate +[openproject@debian]# RAILS_ENV="production" bundle exec rake db:seed +[openproject@debian]# RAILS_ENV="production" bundle exec rake assets:precompile +[openproject@debian]# touch tmp/restart.txt +``` + +*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/). +