v0.x to v1.0 upgrade guide

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 run the migration helpers.

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!

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

EMAIL_FROM=[email protected]
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.

SendGrid has also changed their authentication scheme such that the SENDGRID_USERNAME environment variable must be set to the word apikey, and the SENDGRID_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 SENDGRID_PASSWORD config var on Heroku.

SENDGRID_USERNAME=apikey
SENDGRID_PASSWORD=SG.abcdefghijklmnopqrstuvwxyz