Skip to content

v0.x to v1.0 upgrade guide

Ben Silverman edited this page Sep 16, 2021 · 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 migrate data, run the migration helpers, and set the new environment variables.

Get the new version

First, download the Heroku CLI.

You may then 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

Next, 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.

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!

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 four new variables are:

EMAIL_FROM=[email protected]
EMAIL_PORT=587
EMAIL_SERVER=smtp.sendgrid.net
PROTOCOL=https

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 SendGrid.

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, then your settings will differ.

Clone this wiki locally