Skip to content
Klutch.sh Docs

Deploying an OpenProject App

Introduction

OpenProject is an open-source project management platform with work packages, agile boards, timelines, and docs. Deploying OpenProject with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for attachments and assets—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OpenProject Dockerfile (GitHub is the only supported git source)
  • PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000 and connect on 5432)
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • OpenProject serves HTTP on internal port 8080; choose HTTP traffic.
  • PostgreSQL runs externally over TCP; connect on 5432.
  • Persistent storage is required for attachments and assets.

Repository layout

openproject/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t openproject-local .
docker run -p 8080:8080 \
  -e SECRET_KEY_BASE=changeme \
  -e DATABASE_URL=postgres://user:pass@localhost:5432/openproject \
  openproject-local

Dockerfile for OpenProject (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM openproject/community:13


ENV SERVER_PORT=8080 \
    SECRET_KEY_BASE=changeme


EXPOSE 8080
CMD ["/app/docker/prod/web"]

Notes:

  • Pin the image tag (e.g., 13.x) for stability and upgrade intentionally.
  • If you use custom plugins or themes, add COPY steps and precompile assets if required.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • SERVER_PORT=8080
  • DATABASE_URL=postgres://<user>:<password>@<host>:5432/<db>
  • SECRET_KEY_BASE=<secure-random>
  • Optional: RAILS_ENV=production, SMTP settings (SMTP_ADDRESS, SMTP_PORT, SMTP_USER_NAME, SMTP_PASSWORD, SMTP_DOMAIN, SMTP_ENABLE_STARTTLS_AUTO)

If you deploy without the Dockerfile and need Nixpacks overrides (Rails):

  • NIXPACKS_RUBY_VERSION=3.2.2
  • NIXPACKS_BUILD_CMD=bundle exec rake assets:precompile
  • NIXPACKS_START_CMD=bundle exec puma -C config/puma.rb -p 8080

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/openproject/assets — attachments and assets.
  • /var/openproject/log — logs.

Ensure these directories are writable inside the container.

Deploy OpenProject on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including PostgreSQL connection info and SECRET_KEY_BASE.
  5. Attach persistent volumes for /var/openproject/assets and /var/openproject/log sized for your attachments and logs.
  6. Deploy. Complete any first-run setup at https://example-app.klutch.sh and create your admin user.

Sample API usage

Create an API v3 access token in the UI, then call the API:

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v3/projects" \
  -H "Authorization: Bearer <api_token>"

Create a work package:

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v3/work_packages" \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Hello from OpenProject on Klutch.sh","_links":{"type":{"href":"/api/v3/types/1"},"project":{"href":"/api/v3/projects/1"}}}'

Health checks and production tips

  • Add an HTTP probe to /api/v3/status or / for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Keep database credentials and SECRET_KEY_BASE in Klutch.sh secrets; rotate them regularly.
  • Monitor storage usage on /var/openproject/assets and /var/openproject/log; resize before they fill.
  • Pin image versions and test upgrades in staging; back up database and assets before updates.

OpenProject on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and PostgreSQL connected, you can deliver a robust project management platform without extra YAML or workflow overhead.