Wissen

Migrating between installation types: What to consider when switching OpenProject setups

Veröffentlicht von Corinna Günther 31. März 2025 Geschätzte Lesezeit: 4 Minuten

Whether you’re moving from Docker to a package-based installation, changing databases, or upgrading an older setup, migrating your OpenProject installation can raise important questions. To help you navigate the process, we’ve compiled an overview of supported migration paths, key considerations, and links to detailed documentation. This article gives you the big picture. For in-depth instructions, please refer to our documentation.

Quick navigation overview:

Why switch installations — our recommendation

OpenProject supports several installation methods: Docker, DEB/RPM packages, Helm Charts for Kubernetes, and manual installations. Depending on your infrastructure and technical requirements, one setup may suit you better than another.

For most users, we recommend the Docker-based installation. It’s the easiest to set up, requires minimal system configuration, and is simple to maintain — especially when updating to new OpenProject versions. This makes Docker the most future-proof option.

Wichtig
We will not build packages for new Linux versions (such as Ubuntu 24.04). We will, however, keep releasing new package versions for the currently supported Linux versions until their EOL (end of life). Learn more in our packaged installation documentation.

Migration between Docker and packaged installations

It is possible to migrate between Docker and packaged (DEB/RPM) installations in both directions. In both cases, the process involves:

Exporting the PostgreSQL database,
Copying attachments and configuration files,
Re-importing the data in the new environment.

You might consider migrating to a packaged installation if your IT environment requires tight system-level integration, custom deployment configurations, or traditional OS-based monitoring tools. In this case, please follow this detailed guide in our documentation: Migrating your packaged OpenProject installation to another environment.

On the other hand, migrating from a packaged installation to Docker is a future-proof choice. It simplifies upgrades and deployments — especially since OpenProject will no longer release packages for newer OS versions such as Ubuntu 24.04, and recommends Docker-based installations for long-term use. To switch from packaged to Docker installation, please see this detailed guide in our documentation.

Migration to Kubernetes (Helm)

Migrating to Kubernetes using Helm charts is a powerful option for teams that need to scale OpenProject in dynamic environments or integrate it into an existing Kubernetes infrastructure. This setup is especially relevant for DevOps teams managing multiple services in containers.

While we don’t provide a step-by-step migration guide at this point, the Helm-based deployment is well-documented and maintained. Please note that this path requires advanced Kubernetes and Helm knowledge.

Tipp
Helm-based deployments are ideal for teams with Kubernetes experience. If you’re new to Kubernetes, consider evaluating Docker first — it provides a more accessible starting point with fewer moving parts.

To learn more about the benefits and setup, see this article that compares different OpenProject installation types, with a focus on Helm charts.

Migration between PostgreSQL versions

OpenProject uses PostgreSQL as its database backend. If you’re upgrading PostgreSQL (for example, from version 10 to version 13), you’ll need to migrate the database using a controlled process to avoid data loss or compatibility issues.

We provide specific documentation depending on how OpenProject was installed:

Make sure to create a full backup before performing any PostgreSQL migration.

Tipp
Instead of upgrading the database in place, we recommend doing a backup of OpenProject and restoring it on a newly installed database with the newer version where possible.

Migration from an old MySQL database

If you’re using a much older version of OpenProject, you may not be able to directly upgrade to the current version. In that case, we recommend a fresh installation of the latest version and a manual migration of your data.

This method is especially relevant if you’re switching from an unsupported OS or an outdated setup. Please read our documentation on upgrading older OpenProject versions.

Conclusion: Migrations are manageable

Most migrations between installation types are technically straightforward — especially with a clear plan and the right tools. Always make sure to consult our installation documentation and follow our backup and restore guide before making changes.

If you have questions or want to exchange with other users, feel free to ask in the Community forum.