Jul 16, 2024 3 min read

OpenProject: Self-Hosting Made Simple

OpenProject: Self-Hosting Made Simple
Table of Contents

OpenProject is an open-source project management tool designed for agile teams and organizations needing robust planning, tracking, and collaboration capabilities. It offers unparalleled flexibility for self-hosting, allowing businesses to retain control of their data while accessing features like Gantt charts, time tracking, Kanban boards, and more. This guide walks you through installing, configuring, securing, and managing OpenProject for a fully-functional self-hosted setup tailored to your needs.

Installing OpenProject

πŸ“¦ Docker/Docker Compose Setup

Docker is one of the easiest and most reliable ways to deploy OpenProject. Below is a docker-compose.yml file to set up OpenProject with persistent storage and database integration.

Create a docker-compose.yml file with the following content:


version: '3.3'

services:

openproject:

image: openproject/community:latest

container_name: openproject

ports:

- "8080:80" # Map OpenProject to localhost:8080

environment:

OPENPROJECT_HTTPS: "false" # Set to "true" if running behind HTTPS

volumes:

- openproject_data:/var/db/openproject

- openproject_logs:/var/log/openproject

volumes:

openproject_data:

openproject_logs:

Deploy the setup using Docker Compose:


docker-compose up -d

Check the container status:


docker ps

Access OpenProject in your browser at http://<your-server-ip>:8080.


πŸš€ Manual Installation

For non-Docker users, OpenProject can be installed directly on a Linux server. Below are the steps for Ubuntu-based distributions:

  1. Add the GPG key and repository:

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

sudo add-apt-repository "deb https://dl.packager.io/srv/opf/openproject/stable/ubuntu $(lsb_release -cs) main"

  1. Update and install OpenProject:

sudo apt update

sudo apt install -y openproject

  1. Run the configuration wizard:

sudo openproject configure

Follow the prompts to configure the database, SMTP settings, and other parameters.

  1. Start OpenProject:

sudo systemctl start openproject

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Set up Nginx to forward traffic to OpenProject. Create an Nginx server block by editing or creating /etc/nginx/sites-available/openproject:


server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://127.0.0.1:8080/;

proxy_set_header Host $host;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

Enable the configuration and restart Nginx:


sudo ln -s /etc/nginx/sites-available/openproject /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx


πŸ”’ SSL/TLS Setup

Secure your site with Let's Encrypt:


sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

Automate certificate renewal:


sudo crontab -e

Add this line:


0 0 * * * certbot renew --quiet


πŸ› οΈ Testing and Reloading Nginx

Ensure Nginx is active and error-free:


sudo nginx -t

sudo systemctl restart nginx

Logging and Debugging OpenProject

πŸ—ƒοΈ Enabling Debug Logs

Enable debug logging by setting the logging level in OpenProject’s environment:


docker exec -it openproject bash

export RAILS_LOG_LEVEL=debug

For manual installations, edit the configuration file located in /etc/openproject.


πŸ“„ Viewing Logs

If using Docker:


docker logs openproject

For manual installations:


tail -f /var/log/openproject/production.log


πŸ› οΈ Troubleshooting Common Issues

For errors like database connection issues, check the logs for related messages:


grep "ERROR" /var/log/openproject/production.log


πŸ“€ Exporting Logs

Send logs to an external ELK stack:


docker run -d --name filebeat \

-v /var/log/openproject:/var/log/openproject \

elastic/filebeat:7.17.0

Backup and Restore

πŸ—‚οΈ File-Based Backups

Back up OpenProject’s data directory:


sudo tar -czvf openproject-backup.tar.gz /var/db/openproject


πŸ”„ Database Backups

Dump the PostgreSQL database:


pg_dump -U openproject -h localhost openproject > openproject_db_backup.sql

Restore it:


psql -U openproject -h localhost openproject < openproject_db_backup.sql


πŸ“… Automated Backup Scripts

Create a cron job to automate backups:


crontab -e

Add this:


0 2 * * * tar -czvf /backup/openproject-$(date +\%F).tar.gz /var/db/openproject

Updating and Upgrading OpenProject

⬆️ Updating Docker Images

Update OpenProject in Docker:


docker-compose pull

docker-compose up -d


πŸ› οΈ Manual Updates

For manual installations, upgrade OpenProject via the package manager:


sudo apt update

sudo apt upgrade -y openproject


πŸ” Checking for Updates

Check for updates within OpenProject’s admin interface or by visiting the OpenProject release page.

Leveraging OpenProject’s Unique Features

πŸ”§ Enabling APIs

Activate the API in the admin settings and use the following curl example to access the REST API:


curl -H "Authorization: Token your_api_token" \

-X GET "https://yourdomain.com/api/v3/projects"


🌟 Advanced Configurations

Enable custom plugins by installing them in the plugins directory. For Docker:


docker exec -it openproject bash

bundle exec rake plugin:install NAME=your_plugin_name

For manual installations:


cd /var/db/openproject/plugins

git clone https://github.com/your_plugin/your_plugin.git

bundle install

Wrapping Up

In this guide, we covered installing, configuring, securing, and managing OpenProject with actionable, code-driven steps. Self-hosting OpenProject empowers you with full data control, extensive customization, and access to powerful project management tools. With this guide, you are well-equipped to deploy and optimize OpenProject for your organization’s needs. Dive in and start using OpenProject to supercharge your team's productivity!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.