Top Menu

Jump to content
Home
    • Projects
    • Work packages
    • News
    • Getting started
    • Introduction video
      Welcome to OpenProject Community
      Get a quick overview of project management and team collaboration with OpenProject. You can restart this video from the help menu.

    • Help and support
    • User guides
    • Videos
    • Shortcuts
    • Community forum
    • Professional support

    • Additional resources
    • Data privacy and security policy
    • Digital accessibility (DE)
    • OpenProject website
    • Security alerts / Newsletter
    • OpenProject blog
    • Release notes
    • Report a bug
    • Development roadmap
    • Add and edit translations
    • API documentation
  • Sign in
      Forgot your password?
      Create a new account

      or sign in with your existing account

      Google

Side Menu

  • Overview
  • Activity
  • Roadmap
  • Work packages
  • Calendars
  • Team planners
  • Boards
  • Forums
  • Wiki
    • Table of contents
      • Expanded. Click to collapseCollapsed. Click to showDeveloper
        • Hierarchy leafAccessibility Checklist
        • Hierarchy leafCode Review Guidelines
        • Expanded. Click to collapseCollapsed. Click to showContribution
          • Hierarchy leafGit Workflow
          • Hierarchy leafTranslations
        • Expanded. Click to collapseCollapsed. Click to showDeveloping Plugins
          • Hierarchy leafDeveloping an OmniAuth Authentication Plugin
        • Hierarchy leafRelease Process
        • Hierarchy leafReport a bug
        • Hierarchy leafSecurity
        • Hierarchy leafSetting up an OpenLDAP server for testing
        • Hierarchy leafTheme Features
      • Hierarchy leafDownload
      • Expanded. Click to collapseCollapsed. Click to showFeature tour
        • Hierarchy leafRelease Notes OpenProject 30
        • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 30 - Overview
          • Hierarchy leafGlossary
          • Hierarchy leafRelease Notes - Accessibility
          • Hierarchy leafRelease Notes - Accessibility changes
          • Hierarchy leafRelease Notes - Add work package queries as menu items to sidebar
          • Hierarchy leafRelease Notes - Copy projects based on Templates
          • Hierarchy leafRelease Notes - Design changes
          • Hierarchy leafRelease Notes - Fixed Bugs
          • Hierarchy leafRelease Notes - Keyboard Shortcuts
          • Hierarchy leafRelease Notes - Project settings
          • Hierarchy leafRelease Notes - Ruby&Rails Update
          • Hierarchy leafRelease Notes - Security
          • Hierarchy leafRelease Notes - Timelines
          • Hierarchy leafRelease Notes - Work packages
      • Hierarchy leafHowto create animated gifs
      • Hierarchy leafMigration Squashing
      • Hierarchy leafMod security
      • Hierarchy leafNew work package page
      • Hierarchy leafOP3 to OP4 Debian upgrade
      • Hierarchy leafOP4 Ubuntu1404 Stable with MySQL in production
      • Hierarchy leafOpenProject 40 Development Setup
      • Expanded. Click to collapseCollapsed. Click to showOpenProject Foundation
        • Hierarchy leafBoards
        • Hierarchy leafMembers
        • Hierarchy leafOPF-Meetings
        • Hierarchy leafStatutes
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes
        • Hierarchy leafOpenProject released on Bitnami
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 40 - Overview
        • Hierarchy leafRelease Notes OpenProject 40 - Accessibility improvements
        • Hierarchy leafRelease Notes OpenProject 40 - Column header functions in work package table
        • Hierarchy leafRelease Notes OpenProject 40 - Improved Design
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated query title on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated toolbar on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - OmniAuth integration for OpenProject
        • Hierarchy leafRelease Notes OpenProject 40 - Work package details pane
      • Expanded. Click to collapseCollapsed. Click to showSecurity and privacy
        • Hierarchy leafFAQ
      • Expanded. Click to collapseCollapsed. Click to showSupport
        • Expanded. Click to collapseCollapsed. Click to showDownload and Installation
          • Hierarchy leafInstallation MacOS
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 3 0
            • Hierarchy leafDebian Stable with MySQL in production
            • Hierarchy leafInstallation Ubuntu
            • Hierarchy leafInstallation Windows
            • Hierarchy leafInstallation on Centos 65 x64 with Apache and PostgreSQL 93
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 40
            • Hierarchy leafOP4 Debian Stable with MySQL in production
          • Expanded. Click to collapseCollapsed. Click to showMigration paths
            • Hierarchy leafFrom Chilliproject to OpenProject
            • Hierarchy leafMigration 15 to 30
            • Hierarchy leafMigration 24 to 30
            • Hierarchy leafMigration Redmine 2x › OpenProject 30
            • Hierarchy leafOpenProject 3 Migration
          • Hierarchy leafOpenProject 40
        • Expanded. Click to collapseCollapsed. Click to showNews
          • Hierarchy leafNew OpenProject Translations Plugin
          • Hierarchy leafNew Plugin on OpenProjectorg Local Avatars
          • Hierarchy leafNew design for OpenProject
          • Hierarchy leafNews Accessibility workshop for OpenProject
          • Hierarchy leafNews Glossary for OpenProject
          • Hierarchy leafNews Heartbleed fixed
          • Hierarchy leafNews Icon Fonts
          • Hierarchy leafNews OpenProject 30 Release
          • Hierarchy leafNews Release GitHub Integration Plugin
          • Hierarchy leafNews Success Story Deutsche Telekom
          • Hierarchy leafNews Timelines
          • Hierarchy leafOpenProject 3013 released
          • Hierarchy leafOpenProject 3017 released
          • Hierarchy leafOpenProject 40 released
          • Hierarchy leafOpenProject 40 will be coming soon
          • Hierarchy leafOpenProject 405 released
          • Hierarchy leafOpenProject and pkgrio
          • Hierarchy leafOpenProject news moved to a new blog
          • Hierarchy leafOpenProjectBitnami
          • Hierarchy leafPackager version with plugins released ("Community edition")
          • Hierarchy leafRegistration OpenProject-Foundation
          • Hierarchy leafRelease OpenProject AuthPlugins
          • Hierarchy leafUpdates on OpenProject
          • Hierarchy leafWe need your feedback for the the new fullscreen view for work packages
        • Hierarchy leafOpenProject Plug-Ins
      • Hierarchy leafWiki
You are here:
  • Support
  • Download and Installation
  • Migration paths
  • Migration 24 to 30

Content

Migration 24 to 30

  • More
    • Print
    • Table of contents

OpenProject Migration 2.4 to OpenProject 3.0

This guide describes how to upgrade from OpenProject 2.4 to 3.0 including data migrations.
OpenProject 3.0 requires a new Ruby version, Ruby 2.1.

The guide covers the following steps:

  • Backup
  • Upgrade OpenProject 2.4 to latest version
  • Install OpenProject 3.0 to a new directory and migrate data

If you have any problems along the way, feel free to ask for help in our Support Installation & Updates Forum.

Note: OpenProject 3.0 no longer supports attachments to projects or versions. Before migrating to OpenProject 3.0 you should backup all these attachments or upload them to OpenProject at another place. In case you still have attachments to projects or versions when running the database migrations, they will stop and ask you to delete them.
Note: OpenProject 3.0 no longer includes documents functionality. This functionality has been extracted into the OpenProject Documents plugin. If you want to keep your uploaded documents, you have to add this plugin to your OpenProject installation as described below.

Backup all data

While we try to make things as safe as possible, errors happen and data gets lost. Create a backup to prevent that.

OpenProject has data in these places:

  • Database (see config/database.yml to find out which one is used)
  • openproject directory
  • Attachments are stored by default in openproject/files, in this case no separate backup is necessary.
    • If configured to be stored elsewhere check config/configuration.yml for attachments_storage_path and backup the files stored there.
  • Repositories: If you’re using repositories via reposman.rb, you should back them up. There’s no standard path for them, you can find their path in the cron job running the script or in the individual project settings.

Before continuing, backup all of the data listed above.

Upgrade OpenProject 2.4 to latest version

Before upgrading to 2.4, you need to make sure you have the latest version of 2.4 and have run all database migrations. You’ll have to do this since we squashed most of the previous migrations into a single one for OpenProject 3.0.

The following commands should help you with the upgrade, execute them in the existing openproject directory (assuming you previously cloned the openproject repository).

git fetch
git checkout 2.4.0
bundle install
bundle exec rake db:migrate RAILS_ENV=production

Install OpenProject 3.0

OpenProject 3.0 changes a lot of the underlying technology, e.g. OpenProject 2.4 required plugins to be put within the openproject directory, in the vendor/plugins path. OpenProject 3.0 now uses Gems for plugins. To prevent any remains from 2.4 affecting your 3.0 installation, we recommend installing OpenProject 3.0 in a new folder and start with a fresh clone of the code. If you can use a new machine that’s even better.

You can basically follow the general instructions for installing OpenProject 3.0 (Installation OpenProject 3 0), just make sure to run them in different folder than where your OpenProject 2.4 lies.

Here are some notes on steps you should or should not do while following the installation instructions.

Clone the OpenProject repository and copy files

After this step, you can copy data from your existing OpenProject 2.4 installation to the new OpenProject 3.0 directory. These are the files and folders you should copy:

  • config/database.yml
  • config/configuration.yml
  • files/ (this folder contains all attachments unless moved elsewhere via configuration.yml and attachments_storage_path)

Add plugins

You can follow the installation instructions here. Previously, plugins were copied into openproject/vendor/plugins. With OpenProject 3.0, they’re now Gems, so you can easily add them to the Gemfile.plugins as described in the installation instructions.

If you’re using the documents functionality in OpenProject 2.4, you’ll have to add the following line to the Gemfile.plugins.

gem "openproject-documents", :git => "https://github.com/finnlabs/openproject-documents.git", :branch => "stable"

Configure config/database.yml

You already copied this, so no need to configure from scratch. When using mysql, make sure to use the mysql2 adapter and not mysql.

Create databases

You can skip this step as you’ll keep your database.

Run database migrations and seeds

This step is a bit more complicated than for a fresh installation as you’ll have to run some rake tasks to migrate existing data.

Change timestamps timezone to UTC

The first rake task changes timestamps in the database from your application server timezone to UTC. It takes on parameter as environment variable, FROM. If your OpenProject 2.4 and OpenProject 3.0 application servers and your database server have the same timezone configured, you can skip the FROM parameter. Otherwise you’ll have to set it to your OpenProject 2.4 application server’s timezone in a way that your database understands.

An excerpt from the rake task’s description:

Examples: LOCAL (PostgreSQL), SYSTEM (MySQL), 'Europe/Berlin' (PostgreSQL), Europe/Berlin (MySQL)
(Note the quotes in the different examples)

Here’s the command to run the rake task:

bundle exec rake migrations:change_timestamps_to_utc FROM=<timezone>

Migrations

bundle exec rake db:migrate SECRET_TOKEN=irrelevanthere RAILS_ENV=production

Project and Version Attaachments
If you still have attachments to projects or versions, the migrations will stop here and ask you to run the following rake task.

WARNING: This rake task will delete all remaining attachments to projects and versions. See the beginning of this guide for more information.

bundle exec rake migrations:attachments:delete_from_projects_and_versions

After running the rake task above, continue the migrations with the same command used previously:

bundle exec rake db:migrate SECRET_TOKEN=irrelevanthere RAILS_ENV=production

Documents

If you still have documents in your OpenProject instance and didn’t add openproject-documents to the Gemfile.lock, the rake task will stop and ask you to run a rake task to delete all existing documents.

bundle exec rake migrations:documents:delete

Again, after running the rake task above, continue the migrations with the same command used previously:

bundle exec rake db:migrate SECRET_TOKEN=irrelevanthere RAILS_ENV=production

If you don’t see an error message, the migrations completed successfully.

Once the migrations are done, you can run OpenProject 3.0, see the installation instructions for more information on how to do that.

Note: Please make sure data looks as it should, check especially timestamps of existing data. If they’re wrong, make sure your user account has the correct timezone set, then double check the time zone of your application and database servers.

Again, if you have any problems along the way or want to give feedback to this guide, please create a topic in our Support Installation & Updates Forum.

Loading...