Table of Contents

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


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


Configuration

  1. Login and change admin password
  2. 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


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

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:

  1. Something else is running on the default port 6000 (common since this is the default Ruby-on-Rails port)
  2. 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.