OpenProject

https://www.openproject.org/docs/
Admin
OpenProject is an open-source project management software that enables teams to plan, collaborate,...
Tokens:1,551,074
Snippets:9,691
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Start OpenProject development environment

Source: https://www.openproject.org/docs/development/development-environment/docker/

Copies the docker-compose override file, creates the 'gateway' Docker network, runs the backend setup, installs frontend dependencies, and starts the backend container.

```bash
cp docker-compose.override.example.yml docker-compose.override.yml

# Required: create the `gateway` docker network. Services like hocuspocus
# join it; the optional TLS proxy (see "TLS support" below) and other
# external services such as Nextcloud or Keycloak join the same network
# when present. Safe to run multiple times.
docker network create gateway 2>/dev/null || true

docker compose run --rm backend setup
docker compose run --rm frontend npm install
docker compose up -d backend
```

--------------------------------

### Setup database and install dependencies

Source: https://www.openproject.org/docs/development/development-environment/docker/

Runs database migrations, seeders, and installs server and web dependencies.

```bash
# This will start the database as a dependency
# and then run the migrations and seeders,
# and will install all required server dependencies
docker compose run --rm backend setup

# This will install the web dependencies
docker compose run --rm frontend npm install
```

--------------------------------

### Get branch response example (JSON)

Source: https://www.openproject.org/docs/api/endpoints/custom-fields/

Example response for the GET /api/v3/custom_field_items/{id}/branch endpoint, showing a collection of hierarchy items with their ancestors.

```json
{
  "_type": "Collection",
  "total": 37,
  "count": 37,
  "_embedded": {
    "elements": [
      {
        "_type": "HierarchyItem",
        "id": 1337,
        "label": null,
        "short": null,
        "weight": null,
        "formattedWeight": null,
        "depth": 0,
        "_links": {
          "self": {
            "href": "/api/v3/custom_field_items/1337"
          },
          "branch": {
            "href": "/api/v3/custom_field_items/1337/branch"
          },
          "children": [
            {
              "href": "/api/v3/custom_field_items/1338",
              "name": "Stormtroopers"
            },
            {
              "href": "/api/v3/custom_field_items/1339",
              "name": "Dark Troopers"
            }
          ]
        }
      },
      {
        "_type": "HierarchyItem",
        "id": 1338,
        "label": "Stormtroopers",
        "short": "ST",
        "weight": null,
        "formattedWeight": null,
        "depth": 1,
        "_links": {
          "self": {
            "href": "/api/v3/custom_field_items/1338",
            "name": "Stormtroopers"
          },
          "parent": {
            "href": "/api/v3/custom_field_items/1337",
            "name": "Imperial Troopers"
          },
          "branch": {
            "href": "/api/v3/custom_field_items/1338/branch"
          },
          "children": [
            {
              "href": "/api/v3/custom_field_items/1340",
              "name": "ST-377"
            },
            {
              "href": "/api/v3/custom_field_items/1341",
              "name": "ST-422"
            }
          ]
        }
      },
      {
        "_type": "HierarchyItem",
        "id": 1340,
        "label": "ST-377",
        "short": null,
        "weight": null,
        "formattedWeight": null,
        "depth": 2,
        "_links": {
          "self": {
            "href": "/api/v3/custom_field_items/1340"
          },
          "branch": {
            "href": "/api/v3/custom_field_items/1340/branch"
          },
          "children": []
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/custom_field/42/items"
    }
  }
}
```

--------------------------------

### Copy database.yml.example to database.yml

Source: https://www.openproject.org/docs/installation-and-operations/installation/manual/

Creates the database configuration file from the example template.

```bash
[openproject@host] cp config/database.yml.example config/database.yml
```

--------------------------------

### GET /api/v3/users/{id} - Example Response

Source: https://www.openproject.org/docs/api/endpoints/principals/

Example response for the GET /api/v3/users/{id} endpoint. Shows a user object with fields such as id, name, login, email, status, and _links. The response is in application/hal+json format.

```json
{
  "_type": "User",
  "id": 14,
  "name": "Mara Jade",
  "createdAt": "2022-04-04T08:07:22.910Z",
  "updatedAt": "2024-02-09T09:01:17.382Z",
  "login": "member",
  "admin": false,
  "firstName": "Mara",
  "lastName": "Jade",
  "email": "m.jade@empire.org",
  "avatar": "https://secure.gravatar.com/avatar/17dd23570f3bd129d06db9b48b7a41b8?default=404&secure=true",
  "status": "active",
  "identityUrl": null,
  "language": "en",
  "_links": {
    "self": {
      "href": "/api/v3/users/14",
      "title": "Mara Jade"
    },
    "memberships": {
      "href": "/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2214%22%5D%7D%7D%5D",
      "title": "Memberships"
    },
    "showUser": {
      "href": "/users/14",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/users/14",
      "title": "Update member",
      "method": "patch"
    },
    "lock": {
      "href": "/api/v3/users/14/lock",
      "title": "Set lock on member",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/users/14",
      "title": "Delete member",
      "method": "delete"
    }
  }
}
```

--------------------------------

### GET /api/v3/placeholder_users/{id} - 200 OK Example Response

Source: https://www.openproject.org/docs/api/endpoints/principals/

Example response for a successful GET request to view a placeholder user. The response is in HAL+JSON format and includes the placeholder user's details and links.

```json
{
  "_type": "PlaceholderUser",
  "id": 27,
  "name": "Akolyth",
  "createdAt": "2024-02-12T11:52:24.708Z",
  "updatedAt": "2024-02-12T11:52:24.708Z",
  "_links": {
    "self": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Akolyth"
    },
    "memberships": {
      "href": "/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2227%22%5D%7D%7D%5D",
      "title": "Memberships"
    },
    "updateImmediately": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Update Akolyth",
      "method": "patch"
    },
    "delete": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Delete Akolyth",
      "method": "delete"
    },
    "showUser": {
      "href": "/placeholder_users/27",
      "type": "text/html"
    }
  }
}
```

--------------------------------

### Install dependencies and link modules

Source: https://www.openproject.org/docs/development/development-environment/linux/

Runs the setup script to install gem dependencies, node_modules, link plugin frontend modules, and export frontend localization files.

```bash
bin/setup_dev
```

--------------------------------

### GET /api/v3/notifications - Example Response

Source: https://www.openproject.org/docs/api/endpoints/notifications/

Example JSON response for the GET /api/v3/notifications endpoint. Shows a collection with two notifications, including embedded details and detailsSchemas. The response includes links for self, jumpTo, and changeSize.

```json
{
  "_type": "Collection",
  "count": 2,
  "total": 2,
  "offset": 1,
  "pageSize": 20,
  "_embedded": {
    "elements": [
      {
        "_abbreviated": "Notification resource shortened for brevity",
        "id": 1,
        "readIAN": false,
        "reason": "mentioned"
      },
      {
        "_abbreviated": "Notification resource shortened for brevity",
        "id": 2,
        "readIAN": false,
        "reason": "dateAlert",
        "_embedded": {
          "details": [
            {
              "_type": "Values::Property",
              "property": "startDate",
              "value": "2021-01-01",
              "_links": {
                "self": {
                  "href": "api/v3/notifications/123/details/0"
                },
                "schema": {
                  "href": "api/v3/values/schemas/startDate"
                }
              }
            }
          ]
        }
      }
    ],
    "detailsSchemas": [
      {
        "_type": "Schema",
        "property": {
          "name": "Property",
          "type": "String"
        },
        "value": {
          "name": "Start date",
          "type": "Date"
        },
        "_links": {
          "self": {
            "href": "/api/v3/values/schemas/startDate"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/notifications?offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/notifications?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/notifications?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    }
  }
}
```

--------------------------------

### Copy configuration.yml.example to configuration.yml

Source: https://www.openproject.org/docs/installation-and-operations/installation/manual/

Creates the email notification configuration file from the example template.

```bash
[openproject@host] cp config/configuration.yml.example config/configuration.yml
```

--------------------------------

### Install PostgreSQL server and client

Source: https://www.openproject.org/docs/development/development-environment/linux/

Installs PostgreSQL and its client tools via apt.

```bash
[dev@debian]# sudo apt-get install postgresql postgresql-client
```

--------------------------------

### Run OpenProject configuration wizard

Source: https://www.openproject.org/docs/installation-and-operations/installation/packaged/

Start the OpenProject configuration wizard. Use 'reconfigure' for interactive mode (choices stored in /etc/openproject/installer.dat) or 'configure' for non-interactive mode using stored values.

```bash
sudo openproject reconfigure #interactive - manual choices are stored in /etc/openproject/installer.dat
sudo openproject configure #non-interactive - using values stored in /etc/openproject/installer.dat
```

--------------------------------

### Example: Get relation response (200)

Source: https://www.openproject.org/docs/api/endpoints/relations/

Example JSON response for a successful GET request to /api/v3/relations/{id}. Shows the relation object with its type, reverse type, lag, description, embedded work packages, and links.

```json
{
  "_type": "Relation",
  "id": 650,
  "name": "duplicated by",
  "type": "duplicated",
  "reverseType": "duplicates",
  "lag": null,
  "description": "Those are the same... stupid Stormtroopers!",
  "_embedded": {
    "from": {
      "id": 108,
      "_type": "WorkPackage",
      "_abbreviated": "Work package resource shortened for brevity."
    },
    "to": {
      "id": 78,
      "_type": "WorkPackage",
      "_abbreviated": "Work package resource shortened for brevity."
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/relations/650"
    },
    "updateImmediately": {
      "href": "/api/v3/relations/650",
      "method": "patch"
    },
    "delete": {
      "href": "/api/v3/relations/650",
      "method": "delete,",
      "title": "Remove relation"
    },
    "from": {
      "href": "/api/v3/work_packages/108",
      "title": "Destroy Rebel Base"
    },
    "to": {
      "href": "/api/v3/work_packages/78",
      "title": "Annihilate Yavin 4"
    }
  }
}
```

--------------------------------

### Get current OpenProject version (packaged installation)

Source: https://www.openproject.org/docs/installation-and-operations/operation/control/

Runs the rake task to get the current version of OpenProject.

```bash
sudo openproject run bundle exec rake version
```

--------------------------------

### Start backend server with binding

Source: https://www.openproject.org/docs/development/development-environment/linux/

Start the backend server bound to all network interfaces so it can be accessed from other devices. Use this command after configuring the .env file. If using overmind or bin/dev, edit Procfile.dev accordingly.

```bash
bundle exec rails server --binding=0.0.0.0
```

--------------------------------

### List roles response example

Source: https://www.openproject.org/docs/api/endpoints/roles/

Example response for GET /api/v3/roles, showing a collection of roles with embedded elements.

```json
{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/3",
            "title": "Manager"
          }
        },
        "_type": "Role",
        "id": 3,
        "name": "Manager"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/2",
            "title": "Anonymous"
          }
        },
        "_type": "Role",
        "id": 2,
        "name": "Anonymous"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/5",
            "title": "Reader"
          }
        },
        "_type": "Role",
        "id": 5,
        "name": "Reader"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/4",
            "title": "Member"
          }
        },
        "_type": "Role",
        "id": 4,
        "name": "Member"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/1",
            "title": "Non member"
          }
        },
        "_type": "Role",
        "id": 1,
        "name": "Non member"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/roles"
    }
  },
  "_type": "Collection",
  "count": 5,
  "total": 5
}
```

--------------------------------

### Initialize the database

Source: https://www.openproject.org/docs/installation-and-operations/operation/restoring/

Runs the OpenProject container to initialize the database in the mounted pgdata folder. Stop the container with Ctrl+C after seeing 'Database setup finished.'

```bash
docker run --rm -v /var/lib/openproject/pgdata:/var/openproject/pgdata -it openproject/openproject:17
```

--------------------------------

### Configure and start PostgreSQL 13 (package-based)

Source: https://www.openproject.org/docs/installation-and-operations/misc/migration-to-postgresql13/

Commands to set up the PostgreSQL 13 data directory, include the conf.d directory in postgresql.conf, copy and adjust the custom.conf file, start the new instance, retrieve the database URL, and update the openproject user password.

```bash
sudo su - postgres -c "mkdir -p /var/lib/pgsql/13/data/conf.d"

sudo su - postgres -c "vi /var/lib/pgsql/13/data/postgresql.conf"
# at the section CONFIG FILE INCLUDES, please add the include directory conf.d
include_dir = 'conf.d'

sudo su - postgres -c "cp -p /var/lib/pgsql/10/data/conf.d/custom.conf /var/lib/pgsql/13/data/conf.d/custom.conf"
sudo su - postgres -c "sed -i 's|45432|45433|' /var/lib/pgsql/10/data/conf.d/custom.conf"
sudo su - postgres -c "/usr/pgsql-13/bin/pg_ctl start --wait --pgdata=/var/lib/pgsql/13/data -o '-c config_file=/etc/postgresql/13/main/postgresql.conf'"

# Getting the password for the PostgreSQL database from the configuration
sudo openproject config:get DATABASE_URL
postgres://openproject:[CRYPTICAL-PASSWORD-STRING]@127.0.0.1:45432/openproject

# Alter the password for user openproject in pgsql13
[root@openproject ~]# su - postgres
[postgres@openproject ~]$ psql --port 45432
psql (13.6)
Type "help" for help.
postgres=# ALTER USER openproject WITH PASSWORD '[CRYPTICAL-PASSWORD-STRING]';
ALTER ROLE
postgres=# \q
[postgres@openproject ~]$ logout
```
Tokens:
Raw