Skip to content

Upgrading from DMPonline_v4

Jump to bottom
Brian Riley edited this page Feb 18, 2021 · 44 revisions

Please follow these instructions to upgrade from the DMPonline_v4 codebase. Once you have completed these steps you will be able to run the application directly from the master branch of this repository or via one of our packaged releases (recommended).

Notes:

  • It may be necessary for you to comment out either the pg or mysql2 gems from within the Gemfile depending on which database you use for each of the steps below.
  • The db/schema.rb or Gemfile.lock files may change during each step of the migration process. Running git stash after running each section's upgrade steps will allow you to move on to the next phase.
  • If you have multiple database instances defined in your config/database.yml file, you will want to specify the environment in the rake commands below by appending the environment to the end of each rake task. (e.g. rake db:migrate RAILS_ENV=development)

Pre-upgrade:

  • Clone this repository
  • Copy in the config/database.yml from your current DMPOnline_v4 codebase into the new DMPRoadmap code
  • Make a backup of your database(s)! (e.g. for mysql perform a: mysqldump roadmap --single-transaction --routines=0 --triggers=0 --no-create-db -h[hostname] -u[username] -p > tmp/[environment]_backup_[today].sql or contact your database administrator for assistance)

Upgrade Step 1

Tasks: transition to Rails 4.2, new user permissions and seed new lookup tables

  • git fetch --all
  • git checkout dmponline4_upgrade_step1
  • git pull origin dmponline4_upgrade_step1 This is not necessary if you have just cloned the repo
  • Comment out the pg or mysql2 gem in the Gemfile if necessary
  • bundle install
  • rake db:migrate
  • rake migrate:seed
  • rake migrate:permissions
  • rake migrate:data_integrity WARNING: this step will replace invalid user email addresses with a temporary email address. If it does, it will record the invalid email and the user info in the log/migration.log file. Please review this log after running the script. You may need to contact the user or their organisational admin to get their correct email address. If this file is empty or missing that means that no invalid email addresses were found and all data migrated successfully.
  • git stash

Upgrade Step 2:

Tasks: transformation from dmptemplate-phase-version-section-question to template-phase-section-question and project-plan-section-answer to plan-answer table hierarchies

  • git checkout dmponline4_upgrade_step2
  • git pull origin dmponline4_upgrade_step2 This is not necessary if you have just cloned the repo
  • Comment out the pg or mysql2 gem in the Gemfile if necessary
  • rake db:migrate (can take over 10 minutes depending on size of your database)
  • git stash

Please note: Some users have encountered issues with their template data after running through this step. There is a scenario where your migrated template customizations can end up in a situation where the new customization_of field references a template family_id that does not exist. Templates are versioned in the new codebase. The family_id is used to tie those versions together. The customization_of is used to indicate from which template 'family' the customization was based.

Please run a SELECT * FROM templates WHERE customization_of NOT IN (SELECT DISTINCT family_id FROM templates); query to find any impacted records. Once you have identified the records you can manually update their family_id to point to the correct base template. You may need to refer to your old original dmponline4 database to determine which template to use. See issue #2813 for more details.

Upgrade Step 3:

Tasks: cleanup of temporary structures used in transformation process

  • git checkout dmponline4_upgrade_step3
  • git pull origin dmponline4_upgrade_step3 This is not necessary if you have just cloned the repo
  • Comment out the pg or mysql2 gem in the Gemfile if necessary
  • bundle install
  • rake db:migrate
  • git stash

Upgrade Step 4: (up to v0.3.8)

Once you have finished the data model upgrade process you will need to switch to the master branch and run through any further migrations that may have been introduced since January 2017.

  • git checkout tags/v0.3.8
  • Comment out the pg or mysql2 gem in the Gemfile if necessary
  • cp config/branding_example.yml config/branding.yml
  • Update the config/branding.yml file with your organization's information
  • Copy over the following files from your old DMPonline_v4 directory into the DMPRoadmap directory. If you do not have these files in your old DMPonline_v4 directory you can simply copy the examples provided.
    • config/secrets.yml
    • config/initializers/devise.rb
    • config/initializers/recaptcha.rb
    • config/initializers/wicked_pdf.rb
  • Update your config/initializers/recaptcha.rb file to match the layout in config/initializers/recaptcha.rb.example. The recaptcha gem has been updated and the attribute names have changed. If applicable.
  • bundle install
  • rake db:migrate
  • rake migrate:fix_languages
  • rake migrate:single_published_template
  • rake bugfix:v0_3_3

Upgrade to v1.0.0

  • git checkout tags/v1.0.0
  • bundle install
  • rake db:migrate
  • rake migrate:init_plan_visibility
  • rake migrate:plan_data_contacts
  • rake migrate:move_orcids
  • rake migrate:move_shibs
  • rake upgrade:v1_0_0
  • rake initialize_data:rda_ques
  • We have switched from using rails' asset pipeline to using npm and webpack, see here for details.
  • We have also migrated our themes to a new set, see the Themes wiki page for details on what changed and how to update your data

Theme migrations

Read all about the DMPRoadmap new Themes and how to migrate them for your existing instance on the Themes wiki page.

Next Steps

From here on out, upgrade your tool in accordance with our releases, which can be found here. Pull each one sequentially, install gems or migrate, if gems or migrations have been added, and follow along the instructions with the release. After doing this for all releases, pull the latest code from the Master branch, which may have some bugfixes that have been added since the latest release.

Troubleshooting

  • If you receive complaints about the rake version just prefix the command with bundle exec. This will ensure that the command uses the version of rake defined in the Gemfile.lock (e.g. bundle exec rake db:migrate)
Gem::LoadError: You have already activated rake 12.0.0, but your Gemfile requires rake 11.3.0. Prepending `bundle exec` to your command may solve this.
  • If you receive an error message during migration about Recaptcha and an undefined method called site_key, you should open your config/initializers/recaptcha.rb and comment out the lines. The older code base that we begin the migration from uses an old version of the Recaptcha gem that uses a public_key method. When you are done with the migration, reopen this file and uncomment the lines!

Table of Contents

Clone this wiki locally