OpenProject on AWS User Guide

Overview

This image runs OpenProject, the open source application for classic, agile and hybrid project management and team collaboration. OpenProject brings together work package tracking, Gantt chart planning, agile boards for Scrum and Kanban, time and cost reporting, team wikis, meetings, documents and budgets in a single self hosted web application.

OpenProject is installed from the official vendor package and run as a managed appliance. The appliance runs the Puma application server and a GoodJob background worker, backed by a PostgreSQL 16 database and a memcached cache. nginx terminates port 80 and reverse proxies the application, which listens only on the loopback interface. A single systemd service, openproject.service, supervises the application processes and starts them on boot.

The PostgreSQL database lives at /var/lib/postgresql, which is a dedicated, independently resizable EBS data volume, so your projects and work packages are kept off the operating system disk and survive instance replacement.

A fresh OpenProject install ships a built in administrator account with a well known default password. To make every deployed instance secure, a one shot first boot service generates a unique administrator password, applies it to the administrator account, clears the forced password change prompt, and writes the password to /root/openproject-aws-credentials.txt with mode 0600 so that only the root user can read it. Two instances launched from the same Amazon Machine Image never share an administrator password.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the web interface
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for OpenProject. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger; OpenProject runs PostgreSQL, memcached, the Puma application server and a GoodJob worker together, so it benefits from the memory. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web interface. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation, which generates the administrator password and starts the appliance, takes a couple of minutes after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg OpenProject Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=openproject}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Administrator Password

The administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/openproject-aws-credentials.txt

The file lists the OpenProject URL, the administrator user (admin) and the generated password. Keep this password somewhere safe.

Step 5: Sign In to the Web Interface

The OpenProject web interface is served on port 80 by nginx, which reverse proxies the application. In a browser, go to:

http://<instance-public-ip>/

Sign in as admin with the password from the credentials file. After signing in you land on your account home; open the bundled demo project to explore the project overview, which gathers the project description, status, members, news and the project life cycle.

Work is tracked as work packages. Open Work packages in a project to see the configurable table of tasks, milestones and phases with their type, status, assignee and priority. Filter, group and save views, and create new work packages from the same screen.

The Administration area, reached from the top right account menu, is where you manage users, groups, roles and permissions, work package types and workflows, authentication, email and the rest of the system settings.

Step 6: Confirm OpenProject Is Running

Over SSH, confirm the appliance service is active and that nginx is listening on port 80:

sudo systemctl is-active openproject.service
sudo ss -tlnp | grep ':80 '

You should see the service reported as active and a listener on port 80. The appliance also runs PostgreSQL, memcached, Puma and a GoodJob worker on the loopback interface; you can list the OpenProject units with:

systemctl list-units 'openproject*' --type=service --no-pager

Step 7: Check the OpenProject Version

Confirm the installed OpenProject version with the bundled command line tool:

sudo openproject run bundle exec rake version

Step 8: The Database and the Data Volume

OpenProject stores all of your projects, work packages, users and wiki content in its bundled PostgreSQL database. The database cluster lives on a dedicated EBS volume mounted at /var/lib/postgresql, which keeps it off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/postgresql

To grow the database storage, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Uploaded attachments are stored under /var/db/openproject/files.

Step 9: Use the REST API

OpenProject exposes a REST API on the same port 80, under /api/v3. Create a per user API key from My account then Access tokens in the web interface, and use it with HTTP Basic authentication, sending the user name apikey and your token as the password. For example, from outside the instance, list your work packages with curl -u apikey:<your-token> http://<instance-public-ip>/api/v3/work_packages.

You can confirm the application and its database are healthy at any time with the built in health check endpoint, which returns a plain text report:

curl -s http://127.0.0.1/health_check

A healthy instance reports PASSED for the database schema check and the application status.

Step 10: Add a Custom Domain and Enable HTTPS

The appliance is configured to accept requests on any host name, so it works immediately on the instance's public IP. nginx terminates HTTP on port 80 and reverse proxies the application; its site file is /etc/nginx/sites-available/openproject.

The simplest way to serve OpenProject on your own domain over HTTPS is to place the instance behind an AWS Application Load Balancer with an AWS Certificate Manager certificate that terminates TLS and forwards to port 80. Point a DNS record at the load balancer, and restrict the security group so port 80 is reachable only from the load balancer.

To terminate TLS on the instance itself instead, edit /etc/nginx/sites-available/openproject to add a listen 443 ssl; server block with your certificate and key (for example with Certbot), set server_name to your domain, and reload nginx with sudo nginx -t && sudo systemctl reload nginx. Restrict the security group so ports 80 and 443 are reachable only from the networks that use the application.

Step 11: Backup and Maintenance

Back up OpenProject by snapshotting the /var/lib/postgresql EBS volume, which captures the entire database, together with the attachments under /var/db/openproject/files. The bundled tooling also provides sudo openproject run backup for a consistent application level backup. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; the OpenProject appliance starts automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, project and workflow configuration, user and role management, the REST API, SMTP and email notifications, backups, database tuning, custom domains, TLS and scaling. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.