OpenProject

OpenProject

Changelog

2023-05-00: Init instructions for environment Ubuntu 22.04, OpenProject (13.0.1), PostgreSQL (14.10)
2024-10-15: Update migration instructions for Ubuntu 24.04, Openproject 14.6.1, PostgreSQL 16.4

Why?

For a while I considered jumping over to the original Redmine:

Comparison between OpenProject and Redmine, made 4 years ago

From: https://www.redmine.org/boards/1/topics/56093

And my two cents follow. We're long-term Redmine users and OpenProject was just quickly evaluated. So it is biased indeed.

Redmine over OpenProject:

Redmine is way more friendly for plugin developers. I have the right open-source feeling from it. When i search GitHub:
- There are much more Redmine plugins. Although most of them are dead, sadly.
- Most OpenProject's active plugins are from OpenProject's authors.
OpenProject was forked long time ago and has not adopted some Redmine's development we are used to. Specifically key-value lists in custom fields, which we depend on.
The philosophy of OpenProject's advanced features confuses me - the option of having multivalue lists custom fields is not really an advanced feature (it's possible to work around it or just to purchase it, but still - it makes their business model hardly readable for me).

OpenProject over Redmine:

The UX is awesome compared to Redmine. And it's not only about how it looks. In real life, Redmine discourages our users to share the information at the right place. I believe it is because too high barrier for doing it:
- Any information update looks too formal and binding to the users. I.e. I have an update > locate the Edit option > locate the things I want to update again > do the changes > "commit & push" the changes.
- And when updating, I have a feeling a mistake must not be done, otherwise I'd be punished by the above bureaucratic cycle again and the other users will be bothered by endless issue change log.
- As a result, important information often end up in unstructured instant messaging history, while they were supposed to be at an issue.
- And then the improper information flow costs real money.
Non-geek Redmine users (such us customers) would be probably much less lost in OpenProject.
It looks like a healthier project.
- Redmine development is blocked by people who did a great job in the past, but now they don't have time to touch it for weeks or months. Look at version 4.0 release.
- It does not reflect up-to-date development practices (code in SVN, patches only as attached files). Which makes it also contributor-unfriendly (compare with the UX above).
- In my view, insufficient attention is paid to the PR / funding / contributor aspect. For example, we'd be happy to donate to help Redmine to move forward. But I'm not sure if Redmine is about to move forward even when properly funded - just based on what I see. Instead, funds now go to companies whose business is to make Redmine usable.

To sum it up:

It would be great if Redmine got its momentum again. When there are companies who can live on building Redmine extension layers, it can't be impossible.
OpenProject's dealbreaker for me is that they split up from Redmine completely. If they did it like EasyRedmine, i.e. using plugin and theme-based reworking layer, it would be totally a considerable option.
Currently it's quite difficult for Redmine users to decide where to move on. The main deciding criterion is whether the vanilla Redmine is still alive-enough.

Installation

Bare metal installation instructions for Ubuntu 22.04 below. Better to refer to official documentation for updated instructions. If using other versions like Ubuntu 20.04, swap out the repository, e.g. 22.04.repo -> 20.04.repo:

sudo apt install apt-transport-https ca-certificates wget

# Import PGP key
wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add -

# Import repository
sudo wget -O /etc/apt/sources.list.d/openproject.list \
  https://dl.packager.io/srv/opf/openproject/stable/12/installer/ubuntu/22.04.repo
  
# Install
sudo apt update
sudo apt install openproject

# Configuration
sudo openproject configure

# Route from webserver to internal port

Follow the setup here if Postgres database not already installed.

What's left is to route from webserver to internal port on which Openproject is listening. For nginx, can look something like this:

/etc/nginx/sites-available/openproject

server {
    listen 443 ssl http2;  # remember to add server certificates for HTTPS, usually certbot
    server_name openproject.pyuxiang.com;
    root /opt/openproject/public;
 
    location ^~ / {
        # Include your own authentication layer as desired
 
        proxy_pass http://127.0.0.1:6000;  # use the OpenProject port
        proxy_pass_request_headers on;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_set_header X-Forwarded-Server $host:$server_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Couldn't get docker-compose version to work

Update: A little buggy in configuration.

Instructions directly copied from documentation:

> git clone https://github.com/opf/openproject-deploy --depth=1 --branch=stable/12 openproject
> cd openproject/compose
> docker-compose pull

Configuration

Login and change admin password
Create new users

Backup

Short answer: sudo openproject run backup

If that doesn't work, you need to get your hands a little dirty. For errors relating to PostgreSQL server version mismatch, one possible solution is to change the pgsql binary that OpenProject sees:

sudo openproject config:set PATH=/usr/lib/postgresql/13/bin:/opt/openproject/bin:.......

Run sudo openproject run backup again, and the following logs should appear:

* Generating database backup... done
/var/db/openproject/backup/postgresql-dump-20221227032423.pgdump
* No SVN repositories folder. Ignoring.
* No Git repositories folder. Ignoring.
* Generating attachments backup... done
/var/db/openproject/backup/attachments-20221227032423.tar.gz
* Saving configuration... done
/var/db/openproject/backup/conf-20221227032423.tar.gz

Upgrade

Database migrations are handled by the configure task, so need to run that first. Otherwise a restart loop will occur.

root:~# apt install openproject
root:~# systemctl stop openproject
root:~# openproject configure
root:~# systemctl start openproject

Migration

Last tested 2024-10-15, still working (with Ubuntu 24.04)! This is together with instructions to setup and run a standalone PostgreSQL server:

###################
#  Restore files  #
###################
 
# Restore configuration files and attachments
user:~$ sudo tar xzf attachments-20221227032423.tar.gz -C /var/db/openproject/files
user:~$ sudo tar xzf conf-20221227032423.tar.gz -C /etc/openproject
 
 
##########################################
#  Install standalone PostgreSQL server  #
##########################################
 
# Install Postgres server
user:~$ sudo apt install postgresql postgresql-contrib
user:~$ sudo systemctl enable --now postgresql
 
# Create user
user:~$ sudo -u postgres createuser --interactive
  # Enter name of role to add: openproject
  # Shall the new role be a superuser? (y/n) n
  # Shall the new role be allowed to create databases? (y/n) y
  # Shall the new role be allowed to create more new roles? (y/n) n
 
# Retrieve previous database password
user:~$ sudo cat /etc/openproject/installer.dat | grep password
 
# Assign db password (from above) and create database
user:~$ sudo -u postgres psql
postgres=# \password openproject
  # Enter new password for user "openproject":
  # Enter it again:
postgres=# CREATE DATABASE openproject OWNER openproject;
 
# Modify Postgres authentication method for user
# in "/etc/postgresql/[version]/main/pg_hba.conf"
local all openproject md5
 
# Restart database server
user:~$ sudo systemctl restart postgresql
 
 
#########################
#  Install Openproject  #
#########################
 
# Install dependencies for pulling from openproject repository
user:~$ sudo apt install apt-transport-https ca-certificates wget
 
# Import PGP key and repository (check the latest links!)
user:~$ wget -qO- https://dl.packager.io/srv/opf/openproject/key | sudo apt-key add -
user:~$ sudo wget -O /etc/apt/sources.list.d/openproject.list \
 https://dl.packager.io/srv/opf/openproject/stable/13/installer/ubuntu/22.04.repo
 
# Install openproject
user:~$ sudo apt update
user:~$ sudo apt install openproject
 
# Restore openproject database
# If things fail, consider dropping then recreating the whole database with
# 'DROP DATABASE openproject; CREATE DATABASE openproject OWNER openproject;' 
user:~$ sudo pg_restore --clean --if-exists \
            --dbname $(sudo openproject config:get DATABASE_URL) \
            postgresql-dump-20221227032423.pgdump
 
# Migrate database and set openproject port
user:~$ sudo openproject config:set PORT=6690
user:~$ sudo openproject configure

If this is a standalone server, one will likely need some web server as well. Since I'm much more intimate with nginx as opposed to Apache, my openproject instance is not terminated with TLS (which is instead handled by nginx sitting in front of it).

Here is a sensible default (with some basic security measures without any rate limiting), copied over from nginx on 2024-10-15, with some inspiration from offical openproject documentation and openproject recommended minimal nginx configuration.

Default nginx setup

# Indicate HTTPS proxy on Openproject
user:~$ sudo openproject config:set SERVER_PROTOCOL_FORCE_HTTPS="true"
 
# Install nginx
user:~$ sudo apt install nginx libnginx-mod-http-headers-more-filter
 
# Certificates go here
user:~$ sudo mkdir -p /etc/nginx/certificates
user:~$ sudo mkdir -p /etc/nginx/includes
user:~$ sudo openssl dhparam -out /etc/nginx/includes/dhparam.pem 4096
 
# Load configuration
user:~$ sudo nginx -t
user:~$ sudo nginx -s reload

/etc/nginx/sites-enabled/openproject

server {
    # Webserver configuration
    server_name openproject.pyuxiang.com;
    listen 443 ssl http2;
 
    # Client mTLS configuration (optional)
    ssl_client_certificate certificates/client-ca.pem;
    ssl_verify_client optional;
    if ($ssl_client_verify != SUCCESS) {
        return 301 https://pyuxiang.com;
    }
 
    # Server TLS configuration
    ssl_certificate certificates/server-chain.pem;
    ssl_certificate_key certificates/server-key.pem;
    ssl_session_cache shared:le_nginx_SSL:10m;
    ssl_session_timeout 1d;
 
    # TLS security options, from <https://ssl-config.mozilla.org>
    ssl_dhparam includes/dhparam.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305";
    ssl_prefer_server_ciphers off;
 
    # Force HSTS
    add_header Strict-Transport-Security "max-age=63072000" always;
 
    # Hide server version
    server_tokens off;
    more_clear_headers Server;
 
    # Disable compression to mitigate BREACH
    gzip off;
 
    # Phishing protection
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Cache-Control "no-transform";
 
    # Proxy passing to Openproject HTTP backend
    root /opt/openproject/public;
    location ^~ / {
        proxy_pass http://127.0.0.1:6690;  # use the OpenProject port
        proxy_pass_request_headers on;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_set_header X-Forwarded-Server $host:$server_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 1200s;
        client_max_body_size 10M;
    }
 
    # Disable logging for generic stuff
    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt  { log_not_found off; access_log off; }
 
    # Block access to all hidden files
    location ~* /\. {
        deny all;
    }
}

Troubleshooting

OpenProject unable to connect to database

One possible cause due to PostgreSQL server dying when the server ran out of space (happened to me 2022-10-31 and again 2022-12-19). Need to revive it.

Debugging history

Question was then how to revive it (OpenProject managed the install, but no instructions on how it was installed or debugging it)? Upgrade guide didn't help.

Past wizard configuration details can be found here: sudo cat /etc/openproject/installer.dat

postgres/db_host 127.0.0.1
postgres/db_port 45432
postgres/db_name openproject
postgres/db_username openproject
postgres/addon_version v1
openproject/edition default
postgres/autoinstall install
...

Reinstalling Openproject didn't help either, didn't boot up the auto-installed Postgres database.

Ended up on the database migration page for Postgres v13, which provided the following restart commands for Postgres and solved the problem of database crash.

Older versions of OpenProject can automate installation of PostgreSQL 13, for which the instructions to restart the database is as follows (note also the default logging path to /var/log/syslog):

> sudo ls /var/lib/pgsql/  # check Postgres versions - Openproject 12+ defaults to v13
> sudo apt install postgresql-13  # ensure Postgres is already installed

# Stopping and starting the database
> sudo su - postgres -c "/usr/lib/postgresql/13/bin/pg_ctl stop --wait --pgdata=/var/lib/postgresql/13/main"
> sudo su - postgres -c "/usr/lib/postgresql/13/bin/pg_ctl start --wait --pgdata=/var/lib/postgresql/13/main -o '-c config_file=/etc/postgresql/13/main/postgresql.conf'"

If your system is a bit more modern and has PostgreSQL 14 instead, consider variations based on the different install path:

sudo ls /var/lib/postgresql/  # check Postgres version

502 Bad Gateway

Two causes, either:

Something else is running on the default port 6000 (common since this is the default Ruby-on-Rails port)
Openproject just bugged out :(

First step to look into webserver logs for the cause of 502. If port 6000 is referenced, you know that's the culprit. This port can be changed (avoid low port numbers for obvious reasons):

# Check current port used, e.g. 6000
sudo openproject run env | grep PORT

# Check if port is listening
sudo lsof -nPi | grep 6000

# Change port used
sudo openproject config:set PORT=6600

# Restart OpenProject
sudo openproject restart

If OpenProject still fails to listen on the port (even while status is OK in systemctl), restarting the webserver fixed it for me.

Table of Contents

OpenProject

Why?

Installation

Configuration

Backup

Upgrade

Migration

Troubleshooting

OpenProject unable to connect to database

502 Bad Gateway