Ubuntu 14.04

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

Software Requirements

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

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.

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

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

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

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

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]

Dependency Installation -Node.js

~/var/canvas$ curl -sL https://deb.nodesource.com/setup_4.x | sudo bash -

~/var/canvas$ sudo apt-get install -y nodejs

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

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

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

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

Default Configuration

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

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) default=canvas@example.com

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: "canvas@example.com"

 default_name: "Instructure Canvas"

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"

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)

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 

>

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

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

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.

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

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

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

 *

Configure Passenger

~$ sudo a2enmod passenger

Configure SSL with Apache

~/var/canvas$ sudo a2enmod ssl

~/var/canvas$ sudo service apache2 restart

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.

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:

  ServerName canvas.example.com

  ServerAlias files.canvas.example.com

  ServerAdmin youremail@example.com

  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

  

    Allow from all

    Options -MultiViews

  





  ServerName canvas.example.com

  ServerAlias files.canvas.example.com

  ServerAdmin youremail@example.com

  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

  

    Options All

    AllowOverride All

    Require all granted

  

Modify the following values in the new canvas config file:

  ServerName [value]   -- changed from default

  ServerAlias [value]  -- changed from default

  ServerAdmin [value]  -- changed from default

  DocumentRoot [value] -- default

  ...

  SetEnv [value]       -- default

    -- default

  ...





  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

    -- default

  ...

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

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

restart apache2

sudo service apache2 restart

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

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

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

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

Finish

~$ sudo service apache2 restart

Troubleshooting

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

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

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

Login with local account after LDAP setup

Use URL:

https:///login/canvas

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

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

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

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)