DevOps Guide: Running OpenProject alongside Magento 2

Magento 2 environments are notoriously complex. Adding a Project Management tool like OpenProject to the same server can be risky if dependencies clash. The solution? Docker Isolation.

Step 1: Generate a Unique Security Key

Before launching, generate a random 32-character secret key for session encryption.

head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32 ; echo ''

Step 2: Prepare Host Environment

We store data in /var/www/projects to keep it separate from Magento. Permissions must be set to UID 1000.

sudo mkdir -p /var/www/projects/openproject/{pgdata,assets}
sudo chown -R 1000:1000 /var/www/projects/openproject

Step 3: Deploy via Docker (with SMTP)

docker run -d -p 9999:80 --name openproject \
  -e OPENPROJECT_HOST__NAME=projects.example.com \
  -e SECRET_KEY_BASE="YOUR_KEY" \
  -e OPENPROJECT_HTTPS=true \
  -e OPENPROJECT_EMAIL__DELIVERY__METHOD=smtp \
  -e OPENPROJECT_SMTP__ADDRESS=smtp.sendgrid.net \
  -e OPENPROJECT_SMTP__PORT=587 \
  -e OPENPROJECT_SMTP__USER__NAME="apikey" \
  -e OPENPROJECT_SMTP__PASSWORD="SG.OLD_KEY_HERE" \
  -v /var/www/projects/openproject/pgdata:/var/openproject/pgdata \
  -v /var/www/projects/openproject/assets:/var/openproject/assets \
  --restart unless-stopped \
  openproject/openproject:17

Step 4: Nginx Reverse Proxy Configuration

Map the subdomain projects.example.com to internal port 9999.

server {
    listen 80;
    server_name projects.example.com;
    location / {
        proxy_pass http://127.0.0.1:9999;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Step 5: SSL Activation

sudo certbot --nginx -d projects.example.com

Step 6: Reconfiguring (e.g., Changing SMTP Keys)

One of the best features of Docker is how easy it is to reconfigure. If you need to change your SMTP Password, the Hostname, or any other setting, follow the "Stop-Remove-Start" pattern. Because your data is in a -v volume, your projects are safe.

The Update Process:

1. Stop the container: docker stop openproject
2. Remove the container: docker rm openproject
3. Re-run the command: Simply paste the original command from Step 3, but update the environment variable (e.g., OPENPROJECT_SMTP__PASSWORD="SG.NEW_KEY_HERE").

Note: The application will pick up exactly where it left off because the database is stored on the host machine.

Summary & Key Takeaways