Latest revision as of 08:22, 18 January 2016

Installation Ubuntu 12.04 | Installation Ubuntu 14.04
Canvas - Learning Management Solution. Used by universities and schools.

[edit] Ubuntu 14.04

[edit] Requirements

In the simplest configuration, everything will be running off a single server.

Recommended Hardware specifications

Dual Core+ 3.0ghz+ or Dual processors

4GB+ RAM

60GB HDD

64-bit capable system

[edit] Software Requirements

Minimum, Ubuntu 14.04 LTS+ server edition. Desktop will require more hardware than listed above.

[edit] Recommendations

I would recommend creating a user for installation of the Canvas rather than a unique personal or administrative account. This is because certain files cannot be edited with sudo or it will break canvas.

[edit] Installing PostgreSQL

Postgres (Database)

~$ sudo apt-get update && sudo apt-get -y upgrade && sudo apt-get -y autoremove
~$ sudo apt-get update && sudo apt-get install -y postgresql-9.3

[edit] Configure PostgreSQL

~$ sudo -u postgres createuser canvas -D -S -R -P
~$ sudo -u postgres createdb canvas_production --owner=canvas
~$ sudo -u postgres createdb canvas_queue_production --owner=canvas

[edit] Verify Database Access

Its a good idea to make sure the new user can access the databases you just created.

~$ psql -h localhost -U canvas canvas_production
Password for user canvas: 
psql (9.3.9)
SSL connection (cipher: DHE-RSA-AES256-GCM-SHA384, bits: 256)
Type "help" for help.

canvas_production=> \q

~$ psql -h localhost -U canvas canvas_queue_production
Password for user canvas: 
psql (9.3.9)
SSL connection (cipher: DHE-RSA-AES256-GCM-SHA384, bits: 256)
Type "help" for help.

canvas_queue_production=> \q

[edit] Getting the Code & Installation

~$ sudo apt-get -y install git-core
~$ cd $HOME
~/home/$USER$ git clone https://github.com/instructure/canvas-lms.git canvas
~/home/$USER$ cd canvas
~/home/$USER/canvas$ git branch --set-upstream-to origin/stable
~/home/$USER/canvas$ sudo mkdir -p /var/canvas
~/home/$USER/canvas$ sudo chown -R $USER /var/canvas
~/home/$USER/canvas$ cp -rav /home/$USER/canvas/. /var/canvas

[edit] Dependency Installation -Ruby 2.1.6

You're going to have to add a repository because the version available through Ubuntu's US or Main repos is not up to date (at the time of this writing)

~/var/canvas$ sudo apt-get install -y software-properties-common
~/var/canvas$ sudo apt-add-repository ppa:brightbox/ruby-ng
~/var/canvas$ sudo apt-get update
~/var/canvas$ sudo apt-get install -y ruby2.1 ruby2.1-dev zlib1g-dev libxml2-dev 
~/var/canvas$ sudo apt-get install -y libsqlite3-dev postgresql libpq-dev 
~/var/canvas$ sudo apt-get install -y libxmlsec1-dev curl make g++

Its a good idea to verify you have Ruby 2.1 or higher after installation

~/var/canvas$ ruby -v
ruby 2.1.6p336 (2015-04-13 revision 50298) [x86_64-linux-gnu]

[edit] Dependency Installation -Node.js

~/var/canvas$ curl -sL https://deb.nodesource.com/setup_0.12 | sudo bash -
~/var/canvas$ sudo apt-get install -y nodejs

[edit] Set systemuser as postgres superuser

~/var/canvas$ sudo -u postgres createuser $USER
~/var/canvas$ sudo -u postgres psql -c "alter user $USER with superuser" postgres

[edit] Ruby Gems -Bundler and Canvas dependencies

If you are behind a firewall, you're going to need to open up the following routes to complete this sections' installation instructions:

192.30.252.128:9418

192.30.252.129:9418

192.30.252.130:9418

192.30.252.131:9418

~/var/canvas$ sudo gem install bundler --version 1.7.11

Install bundle. You CANNOT install this as Root, if you do, it will break the application. If you are getting a permissions error, then you did not copy the files to /var/canvas properly as instructed earlier.

~/var/canvas$ bundle install --path vendor/bundle --without=sqlite mysql

[edit] Download default config files from Amazon instance

~/var/canvas$ for config in amazon_s3 database \
  delayed_jobs domain file_store outgoing_mail security external_migration
do cp config/$config.yml.example config/$config.yml; done

[edit] Default Configuration

[edit] database.yml

~/var/canvas$ cp ./config/database.yml.example ./config/database.yml
~/var/canvas$ vi ./config/database.yml

Comment everything except Production if that is all you want.
Under Production

• edit the database name (if different from default)default=canvas_production & canvas_queue_production
• host (if different from default) default=localhost
• username for database user (if different from default) default=canvas
• password for database user

In my instance, nothing was changed except the password.

production:
 adapter: postgresql
 encoding: utf8
 database: canvas_production
 host: localhost
 username: canvas
 password: password
 timeout: 5000
 queue:
   adapter: postgresql
   encoding: utf8
   database: canvas_queue_production
   host: localhost
   username: canvas
   password: password
   timeout: 5000

[edit] outgoing_mail.yml

~/var/canvas$ cp ./config/outgoing_mail.yml.example ./config/outgoing_mail.yml
~/var/canvas$ vi ./config/outgoing_mail.yml

Comment everything except Production if that is all you want.
Under Production

• Edit the address, this should be your email relay or SMTP server
• Edit the port (if different from default) default=25
• Edit the username for your relay/smtp
• Edit the password for your relay/smtp
• Edit the domain (if different from default) default=example.com
• Edit the outgoing address (if different from default) [email protected]

In my instance, I only changed the address, username, password, domain, and outgoing_address

production:
 address: "smtp.example.com"
 port: "25"
 user_name: "user"
 password: "password"
 authentication: "plain" # plain, login, or cram_md5
 domain: "example.com"
 outgoing_address: "[email protected]"
 default_name: "Instructure Canvas"

[edit] domain.yml

~/var/canvas$ cp ./config/domain.yml.example ./config/domain.yml
~/var/canvas$ vi ./config/domain.yml

Comment everything except Production if that is all you want.
Under Production

• Edit the domain
• Uncomment the files domain and add your domain

In my instance, I only changed the domain and uncommented the files domain

production:
 domain: "canvas.example.com"
 # whether this instance of canvas is served over ssl (https) or not
 # defaults to true for production, false for test/development
 ssl: true
 files_domain: "canvasfiles.example.com"

[edit] security.yml

~/var/canvas$ cp ./config/security.yml.example ./config/security.yml
~/var/canvas$ vi ./config/security.yml

Comment everything except Production if that is all you want.
Under Production

• Edit the encryption Key to a minimum of 20 characters. This can be random.

In my instance, I only changed the encryption key by pressing alot of buttons

production:
 # replace this with a random string of at least 20 characters
 encryption_key: hu9ehd92hdh2798ehdrd2hd37824   ---(no this is not really my encryption key)

[edit] Database Population

~/var/canvas$ RAILS_ENV=production bundle exec rake db:initial_setup

You will be asked the following questions:

What email address will the site administrator account use? > 
Please confirm > 
What password will the site administrator use? >
Please confirm >
What do you want users to see as the account name? This should probably be the name of your organization. >

To help our developers better serve you, Instructure would like to collect some usage data about your Canvas installation. You can  
change this setting at any time.:
1. Opt in
2. Only send anonymized data
3. Opt out completely 
>

[edit] Canvas Ownership

I found this to be a required step so that pages would load properly. I could not use www-data.

~/var/canvas$ sudo adduser --disabled-password --gecos canvas canvasuser

[edit] File Generation

~/var/canvas$ mkdir -p log tmp/pids public/assets public/stylesheets/compiled
~/var/canvas$ touch Gemfile.lock
~/var/canvas$ npm install
~/var/canvas$ RAILS_ENV=production bundle exec rake canvas:compile_assets

[edit] Troubleshooting

If the npm install command hangs (just shows |/-\| over and over), stop it and clear out the cache:

~/var/canvas/$ cd ./gems/canvas_i18nliner/
~/var/canvas/gems/canvas_i18nliner$ rm -r ./node_modules/
~/var/canvas/gems/canvas_i18nliner$ npm cache clean

This should clear it up for you and allow you to complete the npm install quickly.

[edit] Private Canvas files Ownership

Limit read access

~/var/canvas$ sudo chown canvasuser ./config/*.yml
~/var/canvas$ sudo chown canvasuser ./config/environment.rb
~/var/canvas$ sudo chmod 400 ./config/*.yml
~/var/canvas$ sudo chown -R canvasuser ./log/ ./tmp/ ./public/javascripts/ ./public/assets/ ./public/stylesheets/compiled/ ./Gemfile.lock ./config.ru

[edit] Apache2 install/config

Unfortunately we need to add a repo before we can install passenger-common1.9.1 as it is not found in the normal 14.04 repo:

E: Unable to locate package passenger-common1.9.1
E: Couldn't find any package by regex 'passenger-common1.9.1'

Add the new repo

~$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7
~$ sudo apt-get install -y apt-transport-https ca-certificates
~$ sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger trusty main > /etc/apt/sources.list.d/passenger.list'
~$ sudo apt-get update

Now you should be able to install the required dependencies. passenger replaces passenger-common1.9.1

~$ sudo apt-get install -y passenger libapache2-mod-passenger apache2

Begin Apache config

~$ sudo a2enmod rewrite
~$ sudo service apache2 restart

[edit] Troubleshooting

If you get the error:
AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1. Set the 'ServerName' directive globally to suppress this message
Do the following and it should resolve the warning:

~/var/canvas$ echo "ServerName localhost" | sudo tee /etc/apache2/conf-available/fqdn.conf
~/var/canvas$ sudo a2enconf fqdn
~/var/canvas$ sudo service apache2 reload
 * Reloading web server apache2
 * 

[edit] Configure Passenger

~$ sudo a2enmod passenger

[edit] Configure SSL with Apache

~/var/canvas$ sudo a2enmod ssl
~/var/canvas$ sudo service apache2 restart

[edit] Generate a CSR for SSL provider

The following will generate a SSL Key w/o a passphrase. Keep in mind that if the key is compromised the SSL traffic is compromised.

openssl genrsa -out server.key 2048

If you've already generated a key with a passphrase and want to remove it, run the following

openssl rsa -in server.key -out server.key.insecure

Now that you have the key you can generate the CSR.

openssl req -new -key server.key -out server.csr

Submit the CSR to your SSL provider and specify what type of system the website is hosted on (ie. apache2 on Linux). They will generally then provide you with the following:

• Root Certificate
• Chain Certificate
• SSL Certificate

I personally check my existing certificates located under /etc/ssl/certs to make sure that neither the Root Certificate or Chain Certificate is already there. If not, then create a new file for each and paste the Root and Chain into each, respectively.
For the SSL certificate, I recommend that you create a sub folder either under /etc/ssl/certs/ or /etc/ssl/private/ and organize the cert, csr, and key under such. Make sure your permissions are set correctly, you do not want just anyone being able to view these files.

[edit] Configure Canvas with Apache2

You should be using Apache 2.4+, make sure you are:

~$ apache2 -v
Server version: Apache/2.4.7 (Ubuntu)
Server built:   Jul 24 2015 17:25:11

Disable default site

~$ sudo a2dissite 000-default.conf
~$ sudo service apache2 reload

Create the canvas apache config file

~/var/canvas$ sudo vi /etc/apache2/sites-available/canvas.conf

Paste the following into the new file:

<VirtualHost *:80>
  ServerName canvas.example.com
  ServerAlias files.canvas.example.com
  ServerAdmin [email protected]
  DocumentRoot /var/canvas/public
  RewriteEngine On
  RewriteCond %{HTTP:X-Forwarded-Proto} !=https
  RewriteCond %{REQUEST_URI} !^/health_check
  RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [L]  
  ErrorLog /var/log/apache2/canvas_errors.log
  LogLevel warn
  CustomLog /var/log/apache2/canvas_access.log combined
  SetEnv RAILS_ENV production
  <Directory /var/canvas/public>
    Allow from all
    Options -MultiViews
  </Directory>
</VirtualHost>
<VirtualHost *:443>
  ServerName canvas.example.com
  ServerAlias files.canvas.example.com
  ServerAdmin [email protected]
  DocumentRoot /var/canvas/public
  ErrorLog /var/log/apache2/canvas_errors.log
  LogLevel warn
  CustomLog /var/log/apache2/canvas_ssl_access.log combined
  SSLEngine on
  BrowserMatch "MSIE [2-6]" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
  BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
  # the following ssl certificate files are generated for you from the ssl-cert package.
  SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
  SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
  SetEnv RAILS_ENV production
  XSendFile On
  XSendFilePath /var/canvas
  PassengerDefaultUser canvasuser
  # PassengerFriendlyErrorPages on
  <Directory /var/canvas/public>
    Options All
    AllowOverride All
    Require all granted
  </Directory>
</VirtualHost>

Modify the following values in the new canvas config file:

<VirtualHost *:80>
  ServerName [value]   -- changed from default
  ServerAlias [value]  -- changed from default
  ServerAdmin [value]  -- changed from default
  DocumentRoot [value] -- default
  ...
  SetEnv [value]       -- default
  <Directory [value]>  -- default
  ...
</VirtualHost>
<VirtualHost *:443>
  ServerName [value]   -- changed from default
  ServerAlias [value]  -- changed from default
  ServerAdmon [value]  -- changed from default
  DocumentRoot [value] -- default
  ...
  SSLCertificateFile [value]    -- changed from default
  SSLCertificateKeyFile [value] -- changed from default
  SetEnv [value]       -- default
  <Directory [value]>  -- default
  ...
</VirtualHost>

Enable the new site

~/var/canvas$ sudo a2ensite canvas.conf
~$ sudo service apache2 restart

Note: Don't forget to publish A records for both canvas.example.com & files.canvas.example.com

[edit] Optimize File Downloads

Pertains to locally stored data

~$ sudo apt-get update && sudo apt-get install -y libapache2-mod-xsendfile
~$ sudo a2enmod xsendfile
~$ sudo service apache2 restart

create new config file to avoid future merge conflicts

~/var/canvas$ cp ./config/environments/production.rb ./config/environments/production-local.rb

Edit ./config/environments/production-local.rb and uncomment

~/var/canvas$ vi ./config/environments/production-local.rb
config.action_dispatch.x_sendfile_header = 'X-Sendfile'

Add the following directives to your apache virtual host config (ie. /etc/apache2/sites-available/canvas)

~$ sudo vi /etc/apache2/sites-available/canvas.conf
XSendFile On
XSendFilePath /var/canvas

I added mine here:

SetEnv RAILS_ENV production
XSendFile On
XSendFilePath /var/canvas
<Directory /var/canvas/public>

restart apache2

sudo service apache2 restart

[edit] Redis Server install

~/var/canvas$ sudo apt-add-repository ppa:chris-lea/redis-server
~/var/canvas$ sudo apt-get update
~/var/canvas$ sudo apt-get -y install redis-server

verify that the redis version installed is 2.6x or above

~/var/canvas$ redis-cli info | grep redis_version
OR
redis-server --version

The above should return a response like such:

redis_version: 2.8.4
OR
Redis server v=3.0.3 sha=00000000:0 malloc=jemalloc-3.6.0 bits=64 build=4284de9902883ae9

[edit] Redis Server config

~/var/canvas$ sudo cp ./config/cache_store.yml.example ./config/cache_store.yml
~/var/canvas$ sudo vi ./config/cache_store.yml

Uncomment the cache_store: redis_store or add the following if there is no production section:

production:
  cache_store: redis_store

~/var/canvas$ sudo cp ./config/redis.yml.example ./config/redis.yml
~/var/canvas$ sudo vi ./config/redis.yml

Uncomment the section below and add localhost

production:
  servers:
   # list of redis servers to use in the ring
  - redis://localhost
#  - redis://redis01

[edit] Secure Redis configs

~/var/canvas$ sudo chown canvasuser ./config/cache_store.yml
~/var/canvas$ sudo chmod 400 ./config/cache_store.yml
~/var/canvas$ sudo chown canvasuser ./config/redis.yml
~/var/canvas$ sudo chmod 400 ./config/redis.yml 

[edit] Automated jobs installation

~/var/canvas$ sudo ln -s /var/canvas/script/canvas_init /etc/init.d/canvas_init
~/var/canvas$ sudo update-rc.d canvas_init defaults
~/var/canvas$ sudo /etc/init.d/canvas_init start

[edit] Finish

~$ sudo service apache2 restart

[edit] Troubleshooting

[edit] syntax error on line 13, col 0: `test:'

Found this was because I had an extra line in my redis.yml file that was uncommented. This came directly from the Amazon examples.

~/var/canvas$ sudo vi ./config/redis.yml
 Comment:
 database: 1

[edit] Permission denied @ unlink_internal - public/javascripts/client_apps/canvas_quizzes.js (Errno::EACCES)

~/var/canvas$ sudo chown -R www-data ./public/javascripts/

[edit] Login with local account after LDAP setup

Use URL:

https://<hostname>/login/canvas

[edit] Jobs are not running

error: /var/canvas/vendor/bundle/ruby/2.1.0/gems/canvas-jobs-0.9.13/lib/delayed/settings.rb:34:in `read': Permission denied @ rb_sysopen - /var/canvas/config/delayed_jobs.yml (Errno::EACCES)

This is generally due to permissions not being set correctly on the config files and environment.rb file. Passenger will choose the user to run the application based on the ownership settings of ./config/environment.rb.

First Try:

~/var/canvas/$ sudo chown canvasuser ./config/environment.rb

Also make sure the following is in place as well:

~/var/canvas$ sudo chown canvasuser ./config/*.yml
~/var/canvas$ sudo chown canvasuser ./config/cache_store.yml
~/var/canvas$ sudo chown canvasuser ./config/redis.yml 

[edit] Passenger not running as correct user

1) make sure that you have the following in your apache config:

PassengerDefaultUser canvasuser

2) make sure that you have made canvasuser owner of /var/canvas/config.ru

~/var/canvas$ sudo chown canvasuser ./config.ru

[edit] We're sorry, but something went wrong.

When trying to go to the site, generally for the first time, if you encounter this error you can add a line to your apache config in order to get more error data to troubleshoot the (generally) passenger error.

~$ sudo vi /etc/apache2/sites-available/canvas.conf

Add the following in your virtual host config. I've already included it in my virtual site conf example, but its commented out so simply uncomment it.

PassengerFriendlyErrorPages on

Restart and take a look at the error details

~$ sudo service apache2 restart

[edit] Permission denied @ rb_sysopen - /var/canvas/config/cache_store.yml (Errno::EACCES)

Assuming that you've turned on friendly error pages for passenger, look to see if passenger is running as the correct user:

HOME = /home/helpdesk
LOGNAME = helpdesk

If it does not say the canvas user you decided to use (generally www-data or canvasuser), like the above does not, then passenger will not run properly.
This can generally be due to a couple of things:

1. You do not have the right file/folder ownership in place
2. You do not have PassengerDefaultUser configured in apache

Go back over and make sure that /var/canvas/config.ru has ownership to the passenger user (in my case it was canvasuser)
Go back over and make sure that your Apache2 config contains PassengerDefaultUser canvasuser (in my case it was canvasuser)