OpenProject Docker and Kubernetes installation

The OpenProject sizing guide gives three starting points for a self-hosted instance: 4 cores and 4 GB of RAM for up to 200 users, 8 cores and 8 GB of RAM for about 500 users, and 16 cores and 16 GB of RAM for about 1,500 users. Treat these as the baseline for the first capacity request to your infrastructure team, not as a verified answer for your organization. They come from the vendor's guidance and describe a typical profile, not a load test run against your data, your network or your usage pattern. Before you order hardware or reserve cloud capacity, decide which tier is closest to your expected named users and write down the assumptions behind that choice. The guide's numbers assume a fairly ordinary workload, and several factors can move your real requirement up or down. The most important are the number of users active at the same time (rather than the number of accounts), how heavily teams use dashboards, Gantt views and reporting, the volume and size of attachments, and which integrations are enabled, such as the Nextcloud link or identity synchronization. The PostgreSQL host matters as much as the application container. If the database shares a machine with the application, or runs on storage with limited IOPS, the database can become the bottleneck long before the application's CPU and memory are exhausted. Ask your installer to state which host runs PostgreSQL and what resources it has. Sizing is not a one-time decision. When user count approaches a tier boundary, such as moving from roughly 200 to 500 users, revisit the allocation before adding people in bulk, because onboarding waves often produce the first slow pages. Plan the resize as a change with a rollback path, and confirm that your Docker or Kubernetes resource limits are updated along with the host. Container memory limits set too low can cause restarts under load, which looks like an application fault but is a configuration issue. In the first few months, measure before you decide whether the tier was right. Track application response times for the pages your teams open most, CPU and memory use of the application and worker containers at peak working hours, PostgreSQL connection counts, slow query logs and disk latency, and growth in attachment storage. Record these weekly for at least the first full project cycle your organization runs. If sustained CPU or memory use stays near the limit at normal peaks, or database latency rises with concurrent users, you have evidence to resize early. If usage stays well below the allocation, you can document a lower tier with confidence for the next budget review. Ask your implementation partner or internal team to confirm three things in writing: the exact sizing guide version they used, the peak concurrent usage they assumed, and the monitoring thresholds that will trigger a resize. A partner that can state these clearly is in a better position to defend the initial sizing and plan the review point.

Before the OpenProject container or package starts, the database has to be PostgreSQL 16 or later. OpenProject has officially supported PostgreSQL 16 since version 16.0.0, and it requires three extensions: pg_trgm, btree_gist and unaccent. Those requirements shape where the database can run. You can use a self-managed server, a virtual machine your team operates, or a managed PostgreSQL service from a cloud provider. Each option moves responsibility differently. A self-managed server gives you full control over versions and extensions, but patching and backups stay with your team. A managed service reduces operational work, but it may restrict what a non-superuser role can install. Before you commit to a managed service, confirm in writing with the provider that the three extensions can be created for the application role you plan to use, and that the major version you need is offered.

Ownership and privileges come next. Create a dedicated database and a login role for OpenProject, and keep administrative accounts out of the application configuration. Decide early who runs the CREATE EXTENSION statements. If the application role owns the database and is allowed to create extensions, the installer can prepare the schema itself. If your policy keeps extension installation with a database administrator, the administrator installs pg_trgm, btree_gist and unaccent beforehand, and the application role only uses them. In either case, the application role should hold no superuser rights. Check the installation documentation for the release you deploy, since it states the privileges the migration step expects. Record the role names and their grants so that an auditor or a new administrator can trace them later.

Keep the database off public networks. Give it a private address, allow inbound connections on the PostgreSQL port only from the hosts or pods that run OpenProject, and deny everything else, including direct access from user workstations. In Kubernetes, express the same rule with network policies, and confirm that your cluster's network plugin enforces them. Require TLS for client connections where your PostgreSQL build and provider support it. Keep the database password in your secrets manager and out of any values file committed to version control. Database administrators should reach the server through a bastion host or a controlled session with logging enabled. Review these rules whenever the topology changes, such as when a managed service is added or a cluster is replaced.

Put extension checks in the verification step so that failures surface before users arrive. After the database is created, query the server version and the pg_extension catalog for the three extension names, and record the output with the change ticket. Run the same check against the exact database the OpenProject installer will use, because a database built for another environment can differ from the one you tested. A missing extension usually appears as a failed migration during installation, which is harder to diagnose than a one-line query run beforehand. Repeat the check after each PostgreSQL major version move or OpenProject upgrade. High availability, replication and backup design belong to the sibling high availability topic, so this section ends once the prerequisites are proven in place.

An OpenProject install is not finished when the containers or pods start. It is finished when a short, fixed set of acceptance checks passes and a failure test shows the platform recovers without losing data. Run these checks in the target environment, using the same reverse proxy, TLS certificate, database and attachment storage that users will reach. Record each result with the date, the version under test and the name of the person who ran it. Your security and operations teams may add checks to this list, but none of the checks below should be dropped before users are invited.

Start with the data path. Confirm that the application connects to the database using its own role, then query the PostgreSQL catalog for the three required extensions: pg_trgm, btree_gist and unaccent. Confirm the server runs PostgreSQL 16 or later, the minimum the system requirements set for current releases. A missing extension is the most common cause of a first-run failure, so treat it as a stop condition and fix it before going further. Next, test attachments. Upload a file to a work package, confirm it appears in the storage the install is configured to use, then download it and compare checksums. In Kubernetes, check the file on the shared volume or object bucket itself, because a file written to pod-local disk will look fine until that pod is replaced.

Next, check the front door. Sign in with a test account over HTTPS and confirm the certificate chain is complete and trusted by a client that has no private root installed. Confirm that plain HTTP redirects to HTTPS and that session cookies carry the secure attributes. Then call the health endpoints both through the reverse proxy and directly against the application service, and confirm both return success. Look up the exact health paths in the release documentation for your version, since they can change between releases. A proxy that returns success while the application is down usually means the health check points at the proxy itself, so compare both results before you accept either one.

The failure test shows whether the install fails safely. Before the test, create a project with several work packages, a comment and an attachment, and note their identifiers. Restart the application container or pod, then restart the database container or pod in a separate step. For each restart, measure how long the service takes to answer again and check the logs for migration errors or repeated crash loops. After recovery, confirm the test records, the attachment and login are intact. Also confirm the failure path: while the database is down, the application should return clear errors rather than accept writes it cannot store. Run this first on a production-like copy, because a database pod restart can expose storage class or reclaim policy problems that only appear under realistic volume handling.

The handover package turns the install into something your team can operate without the implementation partner. It should list the versions in use: the application image tag or package version, the PostgreSQL major and minor version, and the Helm chart version if you deploy that way. Record the sizing tier you chose and the reason for it, stated as the expected user count and the sizing guide tier it maps to, with a note on when to revisit it. Document where configuration and secrets live, such as values files, environment files and the secret store, by location and owner, never by value. Provide the database role inventory: the owner, the application role, any backup or reporting roles, and the privileges each one holds. Finally, include a runbook for the first upgrade rehearsal, following the steps in the sibling topic on OpenProject upgrades and support, and run it against a copy of production data before any live change.