How to Install OpenProject

Step 1: Prepare Your Server

OpenProject requires a Linux server with at least 4 GB of RAM, 2 CPU cores, and 20 GB of available disk space. These are minimum requirements for a small team of 10 to 20 users. For larger teams or heavy use of file attachments, increase RAM to 8 GB and allocate additional disk space accordingly. The background worker process alone requires roughly 4 GB RAM, and each web worker consumes 300 to 400 MB. Plan to run at least 2 web workers for a production deployment, which means 4.6 to 4.8 GB RAM just for the OpenProject services, plus overhead for the operating system, PostgreSQL, and Docker itself.

Supported operating systems include Ubuntu 22.04 or later, Debian 11 or later, CentOS Stream 9, and RHEL 9. Install Docker Engine by following the official Docker documentation for your distribution. Docker Compose is included as a plugin with modern Docker Engine installations and can be verified by running "docker compose version" at the command line. Ensure your server's firewall allows inbound traffic on ports 80 (HTTP) and 443 (HTTPS) if you plan to expose the application directly, or just the port your reverse proxy listens on.

OpenProject requires PostgreSQL 16 or later as of version 16.0.0 of the application. The Docker Compose configuration includes a PostgreSQL container, so you do not need to install the database separately unless you prefer to use an external database server. If you use an external PostgreSQL instance, ensure it is version 16 or higher and that the OpenProject user has permissions to create and manage its database.

Step 2: Create the Docker Compose Configuration

Create a directory for your OpenProject deployment and download the official Docker Compose file from the OpenProject documentation or GitHub repository. The Compose file defines three primary services: the web service (the Rails application serving HTTP requests), the worker service (background jobs for email notifications, PDF exports, and other async tasks), and the database service (PostgreSQL).

Create a .env file in the same directory to configure the deployment. The essential environment variables are OPENPROJECT_SECRET_KEY_BASE (a random string used for session encryption, which you can generate with "openssl rand -hex 32"), OPENPROJECT_HOST__NAME (the fully qualified domain name where the application will be accessible, like "pm.yourcompany.com"), and OPENPROJECT_HTTPS (set to true if you will use SSL). Additional variables control the database connection, email delivery (SMTP server, port, username, password), and the number of web and worker processes.

Review the Compose file to understand the volume mounts. OpenProject stores uploaded files and temporary data in volumes that persist across container restarts. The database volume stores PostgreSQL data. Both must be backed up regularly. If you use an external file storage like NFS or S3, configure the appropriate environment variables to redirect file storage away from the local volume.

Step 3: Launch OpenProject

From the deployment directory, run "docker compose pull" to download the latest container images, then "docker compose up -d" to start all services in detached mode. The first startup is slower because the application runs database migrations to create the schema and seed initial data. Monitor the progress with "docker compose logs -f web" to watch the web service logs. Look for a message indicating that the application is listening for connections, which typically appears as "Puma starting" followed by the bound address and port.

If the logs show database connection errors, verify that the PostgreSQL container is running and healthy with "docker compose ps". Check that the database credentials in your .env file match the PostgreSQL container's configuration. If migrations fail, the logs will include the specific error, which is usually a missing permission or incompatible database version.

Once the application is running, you can access it at http://your-server-ip:8080 (the default port). You should see the OpenProject login page. Do not expose this port to the public internet without setting up a reverse proxy and SSL first.

Step 4: Configure Reverse Proxy and SSL

A reverse proxy sits in front of OpenProject to handle SSL termination, serve static assets efficiently, and provide an additional layer of security. Caddy is the simplest option because it automatically obtains and renews Let's Encrypt certificates. Install Caddy on the host server (not inside Docker), create a Caddyfile that reverse-proxies your domain to localhost:8080, and start the Caddy service. Caddy handles the SSL certificate provisioning, HTTPS redirection, and header forwarding automatically.

If you prefer Nginx, install it alongside Certbot for Let's Encrypt integration. Create a server block that listens on port 443 with SSL, proxies requests to localhost:8080, sets the X-Forwarded-For, X-Forwarded-Proto, and Host headers, and increases the client_max_body_size to accommodate file uploads (64 MB is a reasonable default). Run Certbot to obtain the SSL certificate and configure automatic renewal via a cron job or systemd timer.

After configuring the reverse proxy, update the OPENPROJECT_HOST__NAME and OPENPROJECT_HTTPS variables in your .env file to reflect the domain and HTTPS configuration, then restart the OpenProject containers with "docker compose down" followed by "docker compose up -d". This ensures the application generates correct URLs in emails, API responses, and internal links.

Step 5: Complete Initial Setup

Access OpenProject at your configured domain. The default administrator account uses "admin" as both the username and password. You will be prompted to change the password on first login. After setting a secure password, navigate to Administration to configure the essential settings.

Under General, set the application title and default language. Under Email notifications, configure the SMTP connection so OpenProject can send notifications when issues are updated, assigned, or commented on. Test the email configuration by sending a test message from the administration panel.

Create your first project by clicking the "+" button in the top navigation. Choose a project template if one fits your needs, or start with a blank project. Configure the project modules (work packages, boards, wiki, time tracking) based on your team's workflow. Invite team members by entering their email addresses, which sends registration invitations if they do not already have accounts.

Configure work package types and statuses to match your workflow. OpenProject ships with default types (Task, Milestone, Phase, Feature, Bug, User Story, Epic) and statuses (New, In Progress, Closed, On Hold, Rejected). You can add custom types and statuses, define which transitions are allowed for each role, and set up custom fields for metadata specific to your organization.

Step 6: Set Up Backups

Back up the PostgreSQL database using pg_dump. The command "docker compose exec -T db pg_dump -U postgres openproject > backup.sql" creates a SQL dump of the entire database. Schedule this via cron to run at least once daily, with the output stored in a location outside the Docker volumes. Rotate old backups to prevent disk space exhaustion, keeping at least 7 daily and 4 weekly backups.

Back up the file storage volume that holds uploaded attachments. Use rsync or a similar tool to copy the volume contents to a backup location. If you are using S3 for file storage, your backup strategy should include the S3 bucket in your disaster recovery plan.

Store backup copies in at least one offsite location. This could be an S3 bucket in a different region, a separate server, or even encrypted backups on a different cloud provider. The goal is that a complete server failure does not result in data loss. Test your restore process quarterly by spinning up a fresh OpenProject instance and loading the backup to verify that all data, attachments, and configurations are intact.