Upgrading from DMPonline_v4

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

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
• rake db:migrate
• git stash

Post-upgrade

Once you have finished the 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 master
• git pull origin master This is not necessary if you have just cloned the repo
• 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.
• rake db:migrate
• rake migrate:fix_languages

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!