Upgrading Bitnami Canvas LMS

Background

Canvas LMS, a very famous open source learning management system, can be upgraded following a guide compiled by Canvas LMS developers. The guide, which is available on GitHub, only enlists some very high level tasks involved in the upgradation process. However, the actual upgradation process can be very painful as it can potentially involve many steps of troubleshooting depending on your current version of Canvas LMS.

The upgrade process can become comparatively easy if you are using Bitnami provided Canvas LMS. The recommended procedure in this case is to first launch a new server with latest version of Canvas LMS from an AMI released by Bitnami, move data from your old instance to new instance and finally upgrade the database with latest database changes released by Canvas LMS developers.

Following is a step by step procedure to upgrade AWS Bitnami Canvas LMS.

Prerequisites

Basic understanding of AWS, especially launching and managing AWS EC2 instances. Enough experience working with Linux systems to execute commands, edit files and perform basic troubleshooting. We assume that you have your old EC2 instance up and running and have SSH access to it.

Launch New Instance

1.       Go to Bitnami Canvas LMS web page and find the AMI id for your region. For example, for N.Virginia region and HVM type the AMI id is ‘ami-03a0bc588aeef6936’. You can directly click on AMI id which will take you to AWS EC2 console.

2.       Select instance type (Bitnami recommended is m4.xlarge or higher), EBS volume of at least 30 GB for production environment and complete the launch process

NOTE: It is recommended to disable the option of deleting EBS volume on instance termination. Also, you should check the option of protect against accidental termination of your instance.

Creating Database Dump of Old Canvas LMS

Connect to your old Canvas LMS EC2 instance with default SSH user ‘bitnami’ and create a dump (.sql) backup of your database. Here are some sample commands.

cd ~
pg_dump -U bn_canvaslms bitnami_canvaslms > db-backup.sql

You will be prompted to enter password for the user bn_canvaslms which you can easily retrieved by following command

sudo cat /opt/bitnami/apps/canvaslms/htdocs/config/database.yml

Transferring Database Dump

1.       Copy the .pem private key file of your new instance to the home folder of old instance. You can use WinSCP for this. If you are on linux or mac then do direct scp from terminal.

2.       Once the private key file (.pem) is copied to the old instance run the following command to set proper permissions over it.

sudo chmod 600 {NEW_INSTANCE_PRIVATE_KEYFILE}

3.       Copy the backup to new instance

sudo scp -i /home/bitnami/{NEW_INSTANCE_PRIVATE_KEYFILE} db-backup.sql bitnami@{NEW_INSTANCE_IP}:/home/bitnami/

Move old configurations, brandable CSS and file attachments to new instance. 

Your old instance is likely to have customized Canvas LMS configuration files, a number of files attached to different courses etc. and brandable CSS generated for your Canvas LMS brand. You would need to move all of this to your new instance.

Login to new instance and create directories in /home/bitnami/ as follows:

cd ~
mkdir files config brandable_css_prod

Now, login to your old instance

cd /opt/bitnami/apps/canvaslms/htdocs/tmp
sudo scp -i /home/bitnami/{NEW_INSTANCE_PRIVATE_KEYFILE} -r files/* bitnami@{NEW_INSTANCE_IP}:/home/bitnami/files/

cd /opt/bitnami/apps/canvaslms/htdocs
sudo scp -i /home/bitnami/{NEW_INSTANCE_PRIVATE_KEYFILE} -r config/* bitnami@{NEW_INSTANCE_IP}:/home/bitnami/config/

cd /opt/bitnami/apps/canvaslms/htdocs/public/dist
sudo scp -i /home/bitnami/{NEW_INSTANCE_PRIVATE_KEYFILE} -r brandable_css/* bitnami@{NEW_INSTANCE_IP}:/home/bitnami/brandable_css_prod/

Restoring Database

1.       Get the password for application user user@example.com from file /home/bitnami/ bitnami_credentials. The default user of PostgreSQL is also assigned this password

2.       Login to PostgreSQL using the user ‘postgres’, but first you need to close all connections to the database server

To drop connections:

sudo /opt/bitnami/ctlscript.sh stop
sudo /opt/bitnami/ctlscript.sh start postgresql

psql -U postgres

Enter the password you retrieved in step 1.

3.       To avoid errors due to schema changes, its preferred to drop the database and the restore from the dump file

DROP database bitnami_canvaslms;

create database bitnami_canvaslms;

The password you input in following command needs to be same as in opt/bitnami/apps/canvaslms/htdocs/config/database.yml

alter role bn_canvaslms with password 'BITNAMI_USER_PASSWORD';

grant all privileges on database bitnami_canvaslms to bn_canvaslms;

alter database bitnami_canvaslms owner to bn_canvaslms;

hit ctrl + z

cd ~

psql -U bn_canvaslms bitnami_canvaslms < db-backup.sql

Verify the import by querying any database table

psql -U bn_canvaslms postgres 
\connect bitnami_canvaslms
select * from courses;

Data Migration (update with latest Canvas LMS database updates)

Before running the rake commands to fetch database updates, you might need to do some changes in the redis configuration and update the database encryption. Here is how this can be done.

cd ~
sudo nano /opt/bitnami/redis/etc/redis.conf

In this file comment out the following lines

rename-command FLUSHDB ""
rename-command FLUSHALL ""

Save and exit. Restart Redis

sudo /opt/bitnami/ctlscript.sh stop redis
sudo /opt/bitnami/ctlscript.sh start redis

Now run following

export UPDATE_ENCRYPTION_KEY_HASH=1

sudo /opt/bitnami/use_canvaslms

cd /opt/bitnami/apps/canvaslms/htdocs

RAILS_ENV=production bundle exec rake db:reset_encryption_key_hash

RAILS_ENV=production bundle exec rake db:migrate:predeploy

RAILS_ENV=production bundle exec rake db:migrate

RAILS_ENV=production bundle exec rake db:load_notifications

Restore Old Configurations, file attachments and brandable CSS

login to new instance and run

ls -al /opt/bitnami/apps/canvaslms/htdocs/tmp/files 

This is to see the owner name and group to make sure after copying over the files the permissions, owner and group remains the same

cd ~
sudo cp -r files/* /opt/bitnami/apps/canvaslms/htdocs/tmp/files/
sudo chown -R daemon:daemon /opt/bitnami/apps/canvaslms/htdocs/tmp/files/0000

ls -al /opt/bitnami/apps/canvaslms/htdocs/config

Observe the owner name and group to make sure after copying over the files the permissions, owner and group remains the same

Now comes the tricky part. At this point, you need to find the exact Canvas LMS configurations that you changed in your old instance. Once you have that list you need to copy each file of that list over the Canvas LMS config directories so that every default file is replaced with your old file. It is important to note that you only need to replace the .yml files.

For example:

sudo cp outgoing_mail.yml delayed_jobs.yml brandable_css.yml /opt/bitnami/apps/canvaslms/htdocs/config/

sudo cp locales/*.yml /opt/bitnami/apps/canvaslms/htdocs/config/locales/

sudo cp -r locales/generated/*.yml /opt/bitnami/apps/canvaslms/htdocs/config/locales/generated/

Add the Brandable CSS folder and set proper permissions

ls -al /opt/bitnami/apps/canvaslms/htdocs/public/dist/brandable_css 

Observe the owner name and group to make sure after copying over the files the permissions, owner and group remains the same

sudo cp -r brandable_css_prod/* /opt/bitnami/apps/canvaslms/htdocs/public/dist/brandable_css/

sudo chown -R root:daemon /opt/bitnami/apps/canvaslms/htdocs/public/dist/brandable_css/*

Restart the app

sudo /opt/bitnami/ctlscript.sh restart

You should be able to login with the applications credentials of old instance. 

Muhammad Ali

Bluestack IT Solutions