Skip to content

v0.x to v1.0 upgrade guide

Jump to bottom
Ben Silverman edited this page Mar 29, 2022 · 15 revisions

This guide assumes a Heroku install, which was the primary method supported in DM2 v0.x.

If you have a local install, you can ignore the Heroku specific aspects of this guide—such as prepending heroku run on commands—and just pull the v1.0.0 tag from GitHub. You will still need to install and run Redis, migrate data, run the migration helpers, and set the new environment variables.

Steps to upgrade

  1. Add worker dyno and Heroku Redis addon
  2. Set environment variables
  3. Get the new version
  4. Migrate data

Add worker dyno and Heroku Redis addon

Note: If you are not using Heroku, instead of the steps outlined in this section, you will need to install Redis 6 yourself and have the Redis process (redis-server) running while you run the application.

First, download the Heroku CLI.

You may then run the following commands from a terminal or shell on your local machine:

heroku login

For the following two commands, you may need the flag --app APPNAME where APPNAME is the name of your application on Heroku.

heroku ps:scale worker=1 
heroku addons:create heroku-redis:hobby-dev

If you have trouble using the CLI, you may also do the above steps within the Heroku Dashboard web interface. Those steps can be done by: adding a worker dyno to your dynos, and provisioning a "hobby dev" tier Heroku Redis instance in your Resources.

Set environment variables

In addition, there are several new required or recommended environment variables.

In Heroku, these are called Config Vars and can be accessed from the Settings page of the app. The new variables are:

EMAIL_FROM=[email protected]
EMAIL_PORT=587
EMAIL_SERVER=smtp.postmarkapp.com
MALLOC_ARENA_MAX=2
PROTOCOL=https
REDIS_PROVIDER=REDIS_URL

Set EMAIL_FROM to the email you wish to have system emails sent from, and PROTOCOL to https or http, whichever applies to your app. The above settings for EMAIL_PORT and EMAIL_SERVER are the correct values for Postmark, and the settings for MALLOC_ARENA_MAX and REDIS_PROVIDER are the correct values for Redis/Sidekiq.

Additional instructions for email with Postmark

If using Postmark, our recommended email provider, the EMAIL_USERNAME and EMAIL_PASSWORD must be set as follows: configure a Postmark transactional stream, go to its Settings, and choose "authenticate with an SMTP Token". You will use that token for EMAIL_USERNAME and the provided secret key for EMAIL_PASSWORD.

In addition, your EMAIL_FROM sender must be verified in Postmark for the emails to be delivered.

Additional instructions for email with SendGrid

If using SendGrid, EMAIL_SERVER must be set to smtp.sendgrid.net. SendGrid has also changed their authentication scheme such that the EMAIL_USERNAME environment variable must be set to the word apikey, and the EMAIL_PASSWORD environment variable must be set to an API key itself. The latter must be generated from your Heroku SendGrid instance, accessed from Resources > Twilio SendGrid in Heroku. Once there, navigate to Settings > Create API Key and choose Full Access, then generate the key and paste it into your EMAIL_PASSWORD config var on Heroku.

EMAIL_USERNAME=apikey
EMAIL_PASSWORD=SG.abcdefghijklmnopqrstuvwxyz

If you are using a different email service than SendGrid or Postmark, then your settings will differ. However, all EMAIL-related config variables must be set.

Get the new version

Run the following commands from a terminal or shell on your local machine:

heroku login
git clone https://github.com/performant-software/dm-2.git
cd dm-2
git fetch --tags

Then navigate in a browser to the Settings page for your Heroku instance, and copy the "Heroku git URL".

Let's say your Heroku git URL is https://git.heroku.com/dm.git. You may then run the following commands on your local machine, from the dm-2 directory, to upgrade your Heroku instance to 1.0.0:

git add remote heroku https://git.heroku.com/dm.git
git push heroku v1.0.0^{}:master

Finally, you will need to migrate existing data.

Migrate data

Note: It is recommended to put your Heroku app into Maintenance Mode from the Settings page before running the following commands.

In order to run these migrations on an existing Heroku instance, you can use the following commands via the Heroku CLI. If you don't want to get the Heroku CLI, you may also use the "More > Run Console" option from your Heroku app dashboard.

If using the CLI, you may need the flag --app APPNAME where APPNAME is the name of your application on Heroku.

heroku run rails db:migrate
heroku run rails console

Then, from the Rails console (you should see a prompt that looks like irb(main):001:0>), run the following commands:

LinkMigrationHelper.migrate_link_position!
DocumentLinkMigrationHelper.migrate_document_links!
UserConfirmationMigrationHelper.confirm_approved_users!
HighlightTitleMigrationHelper.convert_excerpts_to_titles!
SearchTextHelper.patch_search_text!

Once each of these migrations has been completed, and you take your app out of Maintenance Mode, you should be ready to go with DM2.1!

Troubleshooting

Authentication errors

If users still cannot log in after the UserConfirmationMigrationHelper.confirm_approved_users! command is run, you can try approving them as well with a script like the following, run from the Rails console (rails console or heroku run rails console):

users = User.all
users.each {|user|
  user.update({approved: true})
  user.confirm
  user.save
}
Clone this wiki locally